FullCash
API
← Início Swagger Ver em markdown

Neste guia

FullCash — Guia de Integração (Contas a Pagar e Arquivos)

Guia para desenvolvedores (e para IAs geradoras de código) entenderem como integrar um sistema externo ao Contas a Pagar do FullCash.

A API é o espelho do papel cliente: você pode ver o que um cliente vê e criar o que um cliente cria — nada além. O fluxo (validar, devolver, rejeitar) é do operador FullCash e não existe na API. O passo do cliente — reenviar para análise uma conta em Pendência — existe — veja Fases de um lançamento.

Base URL

https://api.fullcashbpo.com    endereço da API
/api/v1                        prefixo de todos os endpoints
/docs                          Swagger UI (testar no navegador)
/openapi.json                  contrato OpenAPI
/agente                        base completa para IAs geradoras de código

Autenticação

Toda chamada em /api/v1/* exige a chave no header:

Authorization: Bearer fc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Headers usados na integração:

HeaderDireçãoPara quê
Authorizationvocê → APIBearer fc_live_... em toda chamada
X-FullCash-Companyvocê → APIempresa-alvo quando a chave tem várias
Idempotency-Keyvocê → APIno POST /contas-pagar, evita duplicar
x-request-idAPI → vocêid da requisição (mande para o suporte)
Retry-AfterAPI → vocêquantos segundos esperar depois de um 429
X-FullCash-Event / X-FullCash-Delivery / X-FullCash-SignatureFullCash → seu webhooknome do evento, id da entrega e assinatura

Escolhendo a empresa

Se a chave acessa uma empresa, ela é implícita. Se acessa mais de uma, informe a empresa-alvo em cada request, por uma destas vias (nesta ordem):

  1. Header X-FullCash-Company: <company_id>
  2. Campo company_id no corpo (POST)
  3. Query ?company_id=<company_id>

Empresa fora do conjunto liberado → 403 empresa_nao_liberada.

Rotas de um lançamento (/contas-pagar/{id}, /mensagens, /anexos) não precisam da empresa: a API acha sozinha a dona do lançamento entre as empresas da chave. Se você informar, ela é respeitada (empresa errada → 404). Não chute empresa por empresa.

Homologação

Não existe ambiente separado: a homologação é feita na mesma API, com uma chave de teste que só enxerga empresas de teste (sem lançamento real nem operador real envolvido). Teste o fluxo completo nela — criar, anexar, conversar no chat e receber os webhooks — e só então passe a usar a chave das empresas reais. Os IDs (contas, fornecedores, centros…) de uma empresa não valem em outra: os da homologação respondem 404/422 com a chave de produção.

Escopos

A chave carrega escopos; sem o escopo, a resposta é 403 forbidden_scope.

EscopoLibera
contas_pagar:readlistar/consultar lançamentos
contas_pagar:writecriar lançamento
cadastros:readfornecedores, plano de contas, centros, contas bancárias, usuários, tipos de documento, regras de upload
chat:read / chat:writeler / escrever no chat da conta
anexos:read / anexos:writelistar / enviar anexos (anexo numa mensagem exige chat:write e anexos:write)
arquivos:readler e baixar os arquivos de todos os módulos (anexos, chat e pastas da equipe)

Endpoints

Meta

Lançamentos

Cadastros de apoio (para mandar IDs válidos)

Chat da conta

Quem é o autor. Toda chave tem um usuário de integração próprio (sem login, nome definido pela FullCash, ex.: "Extranet Cliente X") que assina o que chega pela API. Pra dizer quem escreveu de verdade:

CasoO que mandarAparece no FullCash como
Recomendado — qualquer pessoa do seu sistemaautor_externo (só nome é obrigatório)"Murillo Guimarães · via Extranet Cliente X"
Opcional — a pessoa tem conta no FullCash e você quer que conte como delauser_id (de GET /cadastros/usuarios, vinculado à empresa)"Murillo Guimarães", igual a uma mensagem da tela
Nenhum dos dois—"Extranet Cliente X"
{ "message": "Pode seguir com o pagamento",
  "autor_externo": { "nome": "Murillo Guimarães", "email": "murillo@cliente.com", "id": "id-no-seu-sistema" } }

Não precisa criar nem mapear usuário pra usar o autor_externo. user_id e autor_externo juntos → 422; user_id que não é da empresa → 422. O GET /mensagens devolve autor_externo em cada mensagem (ou null), da mais antiga para a mais nova. Mensagens com message_type diferente de user são avisos automáticos do FullCash (ex.: mudança de fase) — mostre como aviso, não como conversa. Chave antiga sem usuário de integração e sem user_id → 422 (peça pra FullCash configurar).

Anexos

Fluxo recomendado para criar com documento: POST /contas-pagar → logo em seguida POST /contas-pagar/{id}/anexos com a NF/boleto.

Arquivos (todos os módulos, só leitura e download)

Os anexos e os arquivos enviados nos chats de todos os módulos (Fechamento de Caixa, Cofre, Contas a Pagar, Agendamento, Conciliação, Solicitações) e as pastas criadas pela equipe, no mesmo modelo do módulo de Arquivos do FullCash: as pastas param no ano (Módulo → Ano) e, dentro do ano, vem a lista com filtros. Escopo arquivos:read.

Pela API, Arquivos é só ler e baixar: não dá para criar, renomear ou apagar pasta, nem enviar ou apagar arquivo — isso é feito pela equipe dentro do FullCash.

Vários registros no mesmo dia (ex.: dois fechamentos em 30/09, cada um com anexo e arquivo de chat): cada linha da lista traz o seu registro e a origem, então nada se mistura. Para o dia inteiro: GET /api/v1/arquivos?modulo=fechamento-caixa&dia=2026-09-30 e agrupe por registro.id.

Regras: só aparecem os módulos ligados na empresa; itens de uso interno nunca aparecem; os chats de grupo da empresa ficam de fora. A data é a do registro (dia do fechamento, vencimento…), não a do envio. Um anexo do lote de agendamento aparece em cada item do lote (do_lote: true) — por isso o .zip dos selecionados usa a linha (chaves), não só o id.

Compatibilidade: os níveis antigos de /pastas (ano → meses, mes → dias, dia → registros) continuam respondendo como antes.

# 1) módulos e os anos de um módulo
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/pastas"
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/pastas?modulo=contas-pagar"
# 2) dentro do ano: opções dos filtros e a lista de outubro, pela data do registro
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/facetas?modulo=contas-pagar&ano=2026"
curl -H "Authorization: Bearer $FC_KEY" \
  "$BASE/api/v1/arquivos?modulo=contas-pagar&ano=2026&mes=10&ordem=data"
# 3) um arquivo (link de 1 h) ou o mês inteiro num .zip
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/<arquivo_id>"
curl -X POST -H "Authorization: Bearer $FC_KEY" -H "Content-Type: application/json" \
  -d '{"modulo":"contas-pagar","ano":2026,"mes":10,"nome":"CP outubro"}' \
  -o cp-outubro.zip "$BASE/api/v1/arquivos/zip"

Criar um lançamento

curl -X POST https://api.fullcashbpo.com/api/v1/contas-pagar \
  -H "Authorization: Bearer fc_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3c-uma-chave-unica-por-lancamento" \
  -d '{
    "tipo_transacao": "saida",
    "status": "a_pagar",
    "valor": 1250.90,
    "data": "2026-09-10",
    "titulo": "NF 12345 — Fornecedor X",
    "fornecedor_id": "UUID_DO_FORNECEDOR",
    "plano_conta_id": "UUID_DE_UMA_FOLHA_DO_PLANO",
    "centro_custo_id": "UUID_DE_CENTRO_DA_EMPRESA",
    "parcelas": [
      { "numero": 1, "total": 2, "vencimento": "2026-10-05", "valor": 625.45 },
      { "numero": 2, "total": 2, "vencimento": "2026-11-05", "valor": 625.45 }
    ]
  }'

Campos

Obrigatórios: titulo, valor (> 0) e data (YYYY-MM-DD). Todo o resto é opcional.

CampoO que é
tipo_transacaosaida (padrão), entrada ou transferencia
statussituação financeira: a_pagar, paga, a_receber, recebida (não é a fase)
descricaotexto livre (ex.: dados de fornecedor ainda não cadastrado)
fornecedor_id, plano_conta_id, centro_custo_idIDs dos cadastros de apoio
conta_bancaria_idconta da empresa (saída/entrada)
conta_origem_id / conta_destino_idsó em transferencia: as duas obrigatórias e diferentes
numero_documentonº da NF/boleto
competenciaYYYY-MM ou MM/YYYY
data_emissaodata de emissão do documento
data_liquidacaodata do pagamento; só vale com status paga/recebida (sem ela, usa data)
tipo_documento, meio_pagamentoum valor das listas de GET /cadastros/tipos-documento
historicohistórico do lançamento
codigo_barraslinha digitável do boleto
parcelaslista de { numero, total, vencimento, valor }: numero (1…N), total (N), vencimento (YYYY-MM-DD), valor. Vazio = parcela única. A API não confere a soma: mande a soma igual a valor
tem_rateio, rateio_tiposmarca o rateio e as dimensões (centro_custo, plano_conta)
company_idempresa-alvo (alternativa ao header)

Resposta 201: { "conta": { ... } } com status_documento: "em_analise", created_via: "api" e o codigo de rastreio (ex.: CP20260007). O valor oficial de cada informação é o campo do lançamento (valor, data…); dados_avancados é só a leitura feita pela IA.

Regras de validação (segurança)

Todas checadas contra a empresa-alvo. Falha → 422 com o campo em details:

CampoRegra
fornecedor_idexiste e é da empresa ou geral
plano_conta_idexiste, ativo e é folha (nivel=conta)
centro_custo_idvinculado à empresa-alvo
conta_bancaria_id, conta_origem_id, conta_destino_idpertencem à empresa-alvo
transferênciaexige origem e destino, diferentes entre si
formatotipos e obrigatórios do corpo (os problemas vêm em details)

Fornecedor ainda não cadastrado

fornecedor_id é opcional e a API não cadastra fornecedor. Se o fornecedor não aparece em /cadastros/fornecedores, crie o lançamento sem fornecedor_id e informe nome e CPF/CNPJ na descricao. O operador cadastra e vincula na análise.

Fases de um lançamento

O campo status_documento diz em que fase do fluxo o lançamento está. Todo lançamento criado pela API nasce em em_analise; as demais transições são feitas pelo operador FullCash — menos a volta da Pendência (pendencias → em_analise), que é do cliente: POST /api/v1/contas-pagar/{id}/reenviar-analise.

⚠️ Use sempre a chave, nunca o rótulo da tela. Por razão histórica, duas chaves têm rótulo trocado: finalizado aparece como Validado e validado aparece como Finalizado.

Chave (status_documento)Rótulo na telaSignificado
em_analiseEm AnáliseRecebido; o operador está conferindo. Toda conta nasce aqui.
pendenciasPendênciasFalta informação ou há inconsistência; voltou para o cliente responder (pelo chat).
finalizadoValidadoConferido e aprovado pelo operador; aguarda o envio ao ERP.
validadoFinalizadoLançado no ERP. Fim do fluxo.
rejeitadoRejeitadoRecusado (inconsistência, prazo ou decisão de uma das partes).

Caminho normal: em_analise → finalizado → validado.

Transições possíveis:

Toda mudança de fase emite o webhook conta.mudou_fase com de e para.

Respondendo uma Pendência (fluxo):

  1. chega conta.mudou_fase com para: "pendencias";
  2. leia o chat (GET /api/v1/contas-pagar/{id}/mensagens) pra ver o que falta;
  3. resolva e chame POST /api/v1/contas-pagar/{id}/reenviar-analise com a resposta em mensagem (arquivo? anexe na mensagem devolvida, em até 2 min);
  4. chega conta.mudou_fase com de: "pendencias", para: "em_analise".

Situação de pagamento é outro campo. Não existe fase "agendado" ou "pago": isso está em status (a_pagar | paga | a_receber | recebida), independente da fase. Mudança em status emite conta.atualizada (não mudou_fase); consulte GET /api/v1/contas-pagar/{id} para ler o valor atual.

Correção de um lançamento já criado. A API não altera lançamentos. Peça a correção pelo chat da conta (POST /api/v1/contas-pagar/{id}/mensagens); o operador ajusta enquanto a conta está em em_analise ou pendencias.

Erros

Formato único:

{
  "error": { "code": "validation_error", "message": "...", "details": [] },
  "request_id": "uuid"
}
HTTPcodequando
400bad_request / empresa_obrigatoriarequest malformado / falta escolher empresa
401invalid_keychave ausente, errada, revogada ou expirada
403forbidden_scope / empresa_nao_liberadasem escopo / empresa fora da chave
404not_foundnão existe ou não é de uma empresa da chave (não vaza existência)
409idempotency_conflictmesma Idempotency-Key com corpo diferente
409idempotency_in_progressa 1ª requisição com essa chave ainda está criando; tente de novo em instantes
409anexo_apos_lancamentoanexo na conta depois da janela de 2 min — envie pelo chat
409conta_fora_de_pendenciareenviar para análise uma conta que não está em Pendência (em_analise = já foi reenviada)
409anexo_fora_da_janelaanexo no chat em mensagem que não é da sua chave ou com mais de 2 min — mande mensagem nova com o arquivo
409conta_finalizadamensagem ou anexo no chat com a conta finalizada (somente consulta) — peça para a FullCash reabrir
410link_expiradopreview_url vencido (30 dias) — pegue um novo no GET
413limite_zip.zip passaria de 500 arquivos ou 1 GB
413corpo_granderequisição grande demais: upload acima de 11 MB (arquivo até 10 MB) ou JSON acima de 1 MB
422validation_errorregra de negócio (fornecedor/plano/centro inválido, arquivo fora das regras de upload, chave sem usuário de integração)
422documento_ilegivela IA não conseguiu ler o documento
429rate_limitedteto por minuto (respeite Retry-After)
500internalerro inesperado do nosso lado — repita com espera e mande o request_id ao suporte
502ia_indisponivel / ia_falhouserviço de leitura por IA fora ou com erro; tente de novo
503db_unavailableAPI sem conexão com o banco — repita com espera
outrohttp_errorerro HTTP genérico do servidor (raro); trate pelo status

Guarde o request_id: ele casa com o log de auditoria do FullCash.

Idempotência

No POST, envie Idempotency-Key única por lançamento. Reenvio com a mesma chave devolve a mesma resposta (não duplica). Mesma chave com corpo diferente → 409 idempotency_conflict.

Webhooks

Quando ativados, o FullCash faz POST na URL cadastrada quando algo muda.

Cadastro. É feito pela equipe FullCash, por chave de API. Informe a URL (HTTPS) e os eventos desejados; devolvemos o segredo (whsec_...) usado na assinatura. O segredo é mostrado uma vez só — guarde-o com segurança.

Eventos e o que vem em data:

EventoQuandodata
conta.criadalançamento criado (API ou tela)conta_id, codigo, titulo, valor, status_documento, created_via
conta.mudou_fasestatus_documento mudou (qualquer transição)conta_id, de, para
conta.atualizadaoutro campo mudou, sem troca de faseconta_id, status_documento
conta.mensagem.novanova mensagem no chat da contaconta_id, message_id
conta.anexo.novonovo anexo do lançamento (não do chat)conta_id, anexo_id

Corpo do evento (exemplo):

{ "id": "uuid-do-evento", "event": "conta.mudou_fase", "created_at": "2026-09-18T12:00:00Z", "company_id": "uuid-da-empresa", "company_sigla": "14A1", "data": { "conta_id": "uuid", "de": "em_analise", "para": "finalizado" } }

Exemplo de verificação (Node):

import { createHmac, timingSafeEqual } from 'node:crypto'
function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(signatureHeader)
  return a.length === b.length && timingSafeEqual(a, b)
}

Limites e boas práticas

RespostaRepetir?
4xx (400, 401, 403, 404, 409, 410, 413, 422)Não. O pedido está errado e vai falhar igual. Corrija o dado (veja error.message) ou registre o erro e siga. 410 = pegue um link novo.
429Sim, depois do Retry-After.
5xx ou falha de redeSim, com espera crescente (ex.: 1, 5, 30 min) e teto de tentativas (ex.: 5). Depois disso, marque como falha e avise alguém.

Mande Idempotency-Key nos POST pra repetir sem risco de duplicar.

FullCash · API de Contas a Pagar · Swagger · openapi.json