SubcontrateiAPI

Respostas, erros e limites ​

Envelope ​

Toda resposta JSON tem a mesma forma:

json
{
  "status": "success",
  "identifier": 1790000000,
  "message": "",
  "data": {},
  "return_type": "SUCCESS"
}
  • status: success, error (recusa ou validação) ou failed (erro interno).
  • identifier: o instante da resposta, em segundos Unix.
  • message: um texto para mostrar ou registrar. Nas recusas, diz o motivo.
  • data: o conteúdo. Nas recusas, traz o código em data.codigo.
  • return_type: o tipo da resposta, em palavras.

O único conteúdo fora do envelope são os XMLs: o do CT-e e o do MDF-e.

Códigos HTTP ​

HTTPreturn_typeQuando
200SUCCESSDeu certo.
201CREATEDEmpresa criada.
202SUCCESSCT-e ou MDF-e recebido: a SEFAZ ainda vai responder. Acompanhe por polling.
400FORBIDDENidempotency_key_ausente: falta o cabeçalho Idempotency-Key.
401UNAUTHORIZEDToken ausente, inválido, vencido ou revogado.
401FORBIDDENassinatura_invalida: a assinatura não confere.
403FORBIDDENA credencial ou a conta não pode fazer a chamada (veja abaixo).
404NOT_FOUNDA empresa ou o documento não existe, é de outra conta ou está fora dos CNPJs da credencial.
409FORBIDDENidempotency_key_reutilizada ou idempotency_key_em_uso (idempotência).
422VALIDATION_ERRORUm campo fora do formato: data.errors traz a lista por campo.
422ERRORRecusa de negócio, com data.codigo.
429TOO_MANY_REQUESTSPassou do limite.
5xxSERVER_ERRORErro interno. Repita com a mesma Idempotency-Key.

Recusas de acesso (403) ​

  • ip_nao_permitido: a credencial tem lista de IPs e o IP da chamada não está nela. A message mostra o IP que chegou.
  • assinatura_inativa: o contrato da API fiscal não está ativo ou a conta não tem assinatura ativa. Fale com a equipe Subcontratei.
  • feature_indisponivel: a rota não está no contrato da conta. data.feature diz qual recurso falta, e a message diz o nome dele. Para incluir, fale com a equipe Subcontratei.
  • empresa_fora_da_integracao: a empresa existe, mas o CNPJ não está entre os permitidos da credencial (também ao cadastrar uma empresa nova).
  • escopo_insuficiente: a credencial não tem o escopo da rota. A recusa traz data.escopo (o exigido pela rota) e data.escopos (os da credencial); compare os dois, ou consulte a credencial.

feature_indisponivel por rota ​

Rotadata.featuremessage
/integracoes/empresasapi-fiscal.empresasO plano da conta não inclui a API fiscal de empresas e certificados.
/integracoes/ctesapi-fiscal.ctesO plano da conta não inclui a API fiscal de CT-e.
/integracoes/mdfesapi-fiscal.mdfesO plano da conta não inclui a API fiscal de MDF-e e CT-e de todos os tipos.
/integracoes/webhooksapi-fiscal.webhooksO plano da conta não inclui os webhooks da API fiscal.

A consulta da credencial aceita integracao.api ou qualquer api-fiscal.*; sem nenhum, a recusa traz data.feature = integracao.api e a message "O plano da conta não inclui a integração por API.".

json
{
  "status": "error",
  "identifier": 1790000000,
  "message": "O plano da conta não inclui a API fiscal de CT-e.",
  "data": {
    "codigo": "feature_indisponivel",
    "feature": "api-fiscal.ctes"
  },
  "return_type": "FORBIDDEN"
}

Recusas de negócio (422) ​

  • operacao_recusada: a situação do documento não permite a ação. A message diz qual.
  • conta_em_homologacao: pediu produção com a conta em homologação.
  • certificado_ausente: a empresa emitente está pendente_certificado. Envie o certificado e emita de novo.
  • ambiente_indisponivel: credencial de produção com a conta ainda em homologação, na emissão fiscal.
  • numero_em_uso: a numeração do CT-e já existe; data.proximo_numero traz o próximo livre.
  • modelo_incompativel: o evento não é do modelo do documento, como carta-correcao numa chave de MDF-e.
  • chave_de_cte: encerramento ou outro evento de MDF-e numa chave de CT-e (e o inverso, nas rotas de MDF-e).
  • documento_encerrado: o documento já está encerrado e não aceita novos eventos.

É um 422 VALIDATION_ERROR, com a mensagem em data.errors["escopos.N"] (N é a posição do escopo pedido). Acontece ao emitir ou alterar uma credencial com um escopo que o plano da conta não inclui. A API não cria credenciais: quem recebe essa recusa é a equipe, ao montar a credencial.

json
{
  "status": "error",
  "identifier": 1790000000,
  "message": "Validation failed",
  "data": {
    "errors": {
      "escopos.0": [
        "O plano da conta não inclui o escopo mdfes:emitir."
      ]
    }
  },
  "return_type": "VALIDATION_ERROR"
}

O 409 cancelamento_ja_solicitado (CT-e e MDF-e) vem quando o cancelamento já foi pedido.

Limites ​

Por credencial, por minuto, somando todos os tokens dela:

  • Leitura (GET): 600 chamadas.
  • Escrita (POST e PUT): 60 chamadas.

Passou do limite: 429, com a message "Limite de chamadas por minuto atingido: aguarde e tente de novo." e o cabeçalho Retry-After com os segundos a esperar. O 429 não conta para a idempotência: depois de esperar, a mesma chave executa.

Os outros limites estão nos campos: até 100 itens por página e até 100 caracteres na Idempotency-Key.

Documentação da API da Subcontratei.