Guia de integração

Este guia cobre o que envolve a emissão de NFS-e além do contrato do endpoint. O contrato em si, com campos, tipos, enums, exemplos de requisição, respostas e payload do callback, está na referência do endpoint.

Como funciona

sequenceDiagram
    autonumber
    participant I as Integrador
    participant S as Safe2Pay
    participant P as SEFIN Nacional / prefeitura
    I->>S: POST /v3/nfse (X-API-KEY + JSON)
    S->>S: Autentica (403), converte o JSON (400), verifica a conta (412), valida o payload (422)
    S-->>I: 202 Accepted (id, status, idempotencyKey)
    S->>S: Verifica idempotência (chave + prestador)
    S->>P: Transmite a DPS
    P-->>S: Autorizada (número, XML) ou rejeitada (código Exxxx)
    S->>I: POST callbackUrl (Identificador, Status, ...)
    I-->>S: 2xx

1. O integrador envia POST /v3/nfse com o header X-API-KEY e o JSON da nota.
2. A Safe2Pay autentica a chave (falha é 403), converte o JSON (falha é 400), verifica se a conta pode emitir (falha é 412) e valida o payload acumulando todos os erros (falha é 422).
3. O pedido válido entra na fila de emissão. Se a emissão estiver indisponível nesse momento, a API devolve 502.
4. A API responde 202 Accepted com data.id, data.status e o eco de idempotencyKey. A nota ainda não existe.
5. A Safe2Pay confere a idempotência (mesma chave e mesmo prestador com nota em curso ou autorizada não gera segunda nota), atribui o número do RPS e transmite a DPS à SEFIN Nacional. A autorização leva cerca de 1 segundo em condições normais.
6. A Safe2Pay envia um POST ao callbackUrl com o desfecho: Status 2 (autorizada) ou Status 9 (rejeitada). O integrador responde 2xx.

Pré-requisitos

Tudo abaixo é feito no painel Safe2Pay antes da primeira chamada. A API verifica cada item na ordem listada e devolve 412 no primeiro que faltar.

Certificado com data de vencimento já passada não bloqueia a chamada (gera apenas aviso interno); a rejeição, se houver, virá da prefeitura pelo callback.

Você também precisa da chave de integração de produção da conta que vai emitir. Não existe sandbox para este endpoint: NFS-e é documento fiscal real e não há prefeitura de homologação disponível ao lojista.

Autenticação

Envie a chave de produção no header X-API-KEY. Não há outro esquema (sem Bearer, sem Basic, sem assinatura). O prestador da nota é o dono dessa chave; não existe campo no payload para emitir em nome de terceiro. Um marketplace não emite pela subconta: a subconta emite com a chave dela.

Toda falha de credencial responde 403 no envelope da API. Não usamos 401 e não enviamos WWW-Authenticate. A chave de sandbox é reconhecida na autenticação, mas recusada em seguida com a mensagem específica abaixo.

A credencial é avaliada antes de qualquer leitura do corpo: uma requisição com chave inválida e JSON malformado recebe 403, não 400. Um 403 nunca enfileira nada: corrija a chave e repita com a mesma idempotencyKey.

Idempotência

idempotencyKey é obrigatória, tem até 64 caracteres e é escolhida por você. Seu escopo é o prestador (a conta da chave). Ela atua em dois momentos.

Na solicitação não há verificação. Cada POST aceito gera um data.id novo e enfileira o pedido; a mesma chave garante apenas que pedidos com ela sejam processados em ordem, um por vez. Reenviar a mesma chave devolve 202 de novo, com id diferente. O 202 não diz "já recebido".

No processamento, antes de transmitir, a Safe2Pay procura uma nota do mesmo prestador com a mesma chave em situação 1 (aguardando), 2 (autorizada) ou 3 (RPS encaminhado). Se achar, o segundo pedido é encerrado sem transmitir nada e você recebe um callback Status 9 com o Identificador do segundo pedido e o erro de chave duplicada. A primeira nota segue normalmente e recebe o próprio callback pelo Identificador original. Resultado: a mesma idempotencyKey nunca gera segunda nota, o que também protege contra o E0014 da SEFIN (DPS duplicada).

O conteúdo do payload não é comparado. Payload diferente com a mesma chave é tratado como duplicata enquanto a primeira nota estiver em 1, 2 ou 3: o segundo payload é descartado. Não devolvemos 409 para esse caso.

Se a nota anterior com aquela chave terminou rejeitada (9) ou cancelada (4), a chave fica livre e um novo POST com ela gera nota nova. Esse comportamento é intencional: a chave volta a servir para um pedido corrigido. A idempotência protege notas válidas e em curso; não é histórico permanente da chave.

Callback

O payload, os campos e os exemplos do callback estão na seção Callbacks da referência do endpoint. Aqui fica o que não cabe no contrato: quando ele é disparado, como responder e o que acontece quando a entrega falha.

Quando é enviado

Status 1 e 3 podem ocorrer e são informativos: não encerram o pedido. O desfecho é sempre 2, 4 ou 9. A autorização na prefeitura leva cerca de 1 segundo e o callback chega logo depois, mas dimensione para atrasos.

Como responder

Responda qualquer status 2xx em menos de 30 segundos. O corpo da resposta é ignorado. Faça o processamento pesado fora do ciclo da requisição.

Processe de forma idempotente: o mesmo callback pode chegar mais de uma vez. Use Identificador + Status como chave de deduplicação. Aceite callbacks com Identificador desconhecido, porque, após um 502 ou timeout no POST, o desfecho real pode chegar no id do primeiro 202 que você não recebeu.

Não há header de autenticação, assinatura HMAC ou token no callback; os headers padrão são limpos antes do envio. A API aceita http:// em callbackUrl, mas use HTTPS: o callback carrega dados da nota.

Retentativa

Se seu endpoint responder não-2xx, a entrega é reagendada com backoff de 15 s, 30 s, 1 min, 2 min, 4 min, 8 min e 8 min: 8 tentativas no total, cerca de 23 minutos e 45 segundos de tolerância. Esgotadas as tentativas, a entrega é encerrada; não há reenvio pela API pública, e o suporte da Safe2Pay precisa ser acionado com traceId e data.id.

Quando não há resposta HTTP (timeout de 30 s, falha de DNS, conexão recusada), a entrega não passa por esse backoff: ela volta pela reentrega interna, cujo número de tentativas e intervalo não são definidos por esta página.

Erros

Os envelopes e exemplos de cada status estão em Responses na referência do endpoint. A ordem de avaliação é: autenticação (403), conversão do JSON (400), estado da conta (412), validação do payload com todos os erros de uma vez (422), documento e município do tomador (422, um erro isolado) e validação fiscal (422 nfse.issuer ou 502).

Erros que só a prefeitura detecta (E0240, E0247, códigos de tributação incorretos) não são 422: passam no 202 e voltam como callback Status 9. As rejeições da SEFIN registradas até aqui são E0240 (endereço do tomador) e E0247 (e-mail do tomador).

Catálogo de name e message

Boas práticas e armadilhas

Endereço completo do tomador. Preencha zipCode (8 dígitos), street, district, cityName, stateCode e municipalityCode coerentes entre si, embora a API exija só number. O E0240 é a rejeição mais frequente em produção e chega pelo callback, depois do 202.

E-mail válido. A API confere apenas a presença de um @ com texto antes e depois; a SEFIN rejeita com E0247. Valide o formato completo antes de enviar.

Código IBGE sempre vence. Com address.municipalityCode de 7 dígitos, cityName e stateCode não são usados para resolver. Código com tamanho diferente de 7 é ignorado em silêncio. Sem código válido, a busca por cityName + stateCode precisa achar exatamente um município; não há aproximação. Mesmo com o código informado, cityName continua obrigatório na validação fiscal.

Documento só com dígitos. identity segue como enviado: 12345678909 e 11222333000181, nunca com pontuação. Um CPF com máscara pode atravessar a validação e chegar pontuado à prefeitura.

Códigos de tributação com a contabilidade. nationalTaxCode (6 dígitos), serviceListItem, municipalTaxCode e nbsCode (9 dígitos) não são validados semanticamente. Código errado atravessa tudo e vira rejeição ou nota errada na prefeitura.

Booleanos são true/false. Nunca 0, 1 ou 2. Enviar número gera 400, e é bom que gere: num documento fiscal, um valor ambíguo poderia declarar o oposto do pretendido.

Decimais como número JSON, com ponto e duas casas. 1000.00, não 1.000,00. O conversor tolera string numérica, mas o contrato é número JSON; não dependa da tolerância.

Aritmética dos valores é sua. A API só valida amount > 0. amountTaxBase é recalculado como amount - amountDeductions; amountPis e amountCofins zerados são calculados a partir das alíquotas; amountNet vai como informado. A prefeitura pode recusar inconsistências.

serviceDate não pode estar no futuro, em horário de Brasília. Faturamento gerado à meia-noite UTC com a data do dia seguinte é recusado com 422.

Retry só em 502, 500 e timeout, sempre com a mesma idempotencyKey. Backoff de minutos, não segundos.

Leia o status HTTP antes da mensagem. 400 corrige o tipo; 422 corrige o payload (a lista é completa); 412 corrige no painel; 502 repete depois; 403 corrige a chave.

Receptor de callback idempotente e rápido. Deduplique por Identificador + Status, responda 2xx em menos de 30 s, aceite Identificador desconhecido após 502 ou timeout no POST.

Não ecoe nem logue dados pessoais. O payload carrega nome, CPF/CNPJ, e-mail e endereço do tomador (LGPD). A resposta 202 propositalmente não os devolve; seu log também não deve.

O prestador é o dono da chave. Marketplace não emite pela subconta; a subconta emite com a chave dela.

Limites e tamanhos

Glossário