Lançamentos
Lançamento (rascunho) é diferente de emissão: um rascunho fica salvo pra conferência antes de qualquer coisa acontecer de verdade. Documentos de saída transmitem à SEFAZ só quando confirmados; documentos de entrada nunca transmitem nada -- a nota já foi emitida por outra parte, aqui você só registra o recebimento.
Lançamento de saída POST
Corpo idêntico ao de NF-e · Emitir, só que salvo como rascunho em vez de transmitido na hora.
| Campo | Obrigatório | Observação |
|---|---|---|
document_type | Sim | NFE (modelo 55) ou NFCE (modelo 65). |
tipo_operacao | Não | SAIDA (padrão) -- lançamento de entrada usa o endpoint próprio abaixo. |
finalidade | Não | NORMAL (padrão), COMPLEMENTAR, AJUSTE, DEVOLUCAO, CREDITO, DEBITO. |
destinatario_documento | Sim p/ NF-e | Precisa já existir em Tomadores. |
itens | Sim | Array de {codigo_produto, quantidade, valor_unitario?} -- codigo_produto referencia o catálogo de Produtos. |
referenciados, transportador, pagamentos, parcelas, informacoes_complementares | Não | Mesmo formato de NF-e · Emitir. |
curl -X POST https://areacliente.centralfiscal.com.br/v1/contribuintes/{contribuinte_id}/lancamentos \
-H "Authorization: Bearer cf_live_51JqK..." \
-H "Content-Type: application/json" \
-d '{
"document_type": "NFE",
"destinatario_documento": "98765432000110",
"itens": [{"codigo_produto": "SKU-001", "quantidade": 10}]
}'Lançamento de entrada POST
tipo_entrada="TERCEIRO" (padrão) -- nota já emitida por um fornecedor, você só
escritura o recebimento. tipo_entrada="PROPRIA" -- compra de pessoa física/
sucateiro sem IE (quem vende não é obrigado a emitir nota fiscal, Convênio SINIEF s/nº de
15/12/1970, art. 54, I).
| Campo | Obrigatório | Observação |
|---|---|---|
tipo_entrada | Não | TERCEIRO (padrão) ou PROPRIA. |
fornecedor_documento | Sim | Fornecedor (TERCEIRO) ou CPF do vendedor (PROPRIA). |
numero_documento_origem, serie_documento_origem | Sim p/ TERCEIRO | Nunca exigido em PROPRIA (não existe nota do vendedor). |
cfop | Sim p/ PROPRIA | Restrito a 1101, 1102, 1904 (retorno MEI) ou 1949. |
natureza_operacao | Sim p/ PROPRIA | Ex. "Compra de sucata de pessoa física não contribuinte". |
chave_acesso_origem | Não | 44 dígitos, quando disponível. |
itens | Sim | Array de {descricao, quantidade, valor_unitario?}. |
curl -X POST https://areacliente.centralfiscal.com.br/v1/contribuintes/{contribuinte_id}/lancamentos/entrada \
-H "Authorization: Bearer cf_live_51JqK..." \
-H "Content-Type: application/json" \
-d '{
"tipo_entrada": "TERCEIRO",
"fornecedor_documento": "11222333000181",
"numero_documento_origem": "12345",
"itens": [{"descricao": "Matéria-prima", "quantidade": 100, "valor_unitario": 3.2}]
}'Importar XML de entrada POST
Lê um XML de NF-e real (nunca altera o arquivo original -- fica preservado dentro do
lançamento) e cria um rascunho de entrada já preenchido (fornecedor, itens, chave de acesso).
Bloqueia (409) reimportar a mesma chave de acesso duas vezes. Aceita multipart/form-data
(campo arquivo) ou JSON {"xml": "<NFe>...</NFe>"}.
curl -X POST https://areacliente.centralfiscal.com.br/v1/contribuintes/{contribuinte_id}/lancamentos/entrada/importar-xml \
-H "Authorization: Bearer cf_live_51JqK..." \
-F "arquivo=@nota-recebida.xml"Consultar, editar, confirmar, descartar
| Endpoint | Descrição |
|---|---|
GET /v1/contribuintes/{id}/lancamentos | Lista todos os lançamentos (?status=RASCUNHO|CONFIRMADO|ESTORNADO opcional). |
GET /v1/contribuintes/{id}/lancamentos/{lancamento_id} | Consulta um lançamento (inclui o XML original, se foi importado). |
POST /v1/contribuintes/{id}/lancamentos/{lancamento_id}/editar | Edita um lançamento de entrada ainda em rascunho -- mesmo corpo do POST de criação. Bloqueia (409) se já confirmado/estornado. Saída ainda não tem edição por API (descarte e relance). |
POST /v1/contribuintes/{id}/lancamentos/{lancamento_id}/confirmar | Saída: despacha pro motor fiscal de verdade (mesmo pipeline do NF-e · Emitir). Entrada: só marca CONFIRMADO, nunca transmite nada. |
POST /v1/contribuintes/{id}/lancamentos/{lancamento_id}/estornar | Descarta um rascunho (nunca um já confirmado). |
Resposta da confirmação
// Saída confirmada -- mesmo formato de NF-e · Emitir
{
"ambiente": "PRODUCTION",
"status": "AUTHORIZED",
"chave": "43...",
"numero_documento": "1002",
"transmissao_id": "..."
}
// Entrada confirmada -- nunca transmite nada
{
"ambiente": "PRODUCTION",
"status": "CONFIRMADO",
"tipoOperacao": "ENTRADA",
"mensagem": "Entrada registrada -- nenhum documento foi transmitido a SEFAZ (a nota já foi emitida pelo fornecedor)."
}RASCUNHO, pode ser confirmado de novo depois de corrigido (mesma
disciplina do resto da API: número de nota só é consumido quando autorizada).