{ "openapi": "3.0.3", "info": { "title": "ZP — APIs de terceiro", "version": "1.0.0", "description": "APIs para integrar sistemas de terceiros (ERP, software house…) ao ZP: cobrança, cartão e documentos fiscais.\n\n**Autenticação**: todo pedido leva na query o identificador do perfil (`APP`, `REDE`, `CNPJ` ou `CPF`), a `SENHA` do dia e `A` (id do app). `SENHA = md5(identificador + AAAA-MM-DD + valor enviado em APP/REDE/CNPJ/CPF)`, com a data de Brasília (vale ontem, hoje e amanhã). O identificador é fornecido pela TX Fuel e deve ser guardado em segredo.\n\nManual completo: https://wiki.txfuel.com.br/pt-br/zp/api", "contact": { "name": "Suporte TX Fuel", "email": "suporte@txfuel.com.br" } }, "servers": [ { "url": "https://zp1.txfuel.com.br/api", "description": "Servidor 1" }, { "url": "https://zp2.txfuel.com.br/api", "description": "Servidor 2" } ], "tags": [ { "name": "Cobranças", "description": "Emissão, consulta e cancelamento de cobranças por boleto, PIX e cartão de crédito (uma ou várias por chamada, em lote), acompanhamento dos lotes e cofre de cartões usados nas cobranças por cartão." }, { "name": "Cedentes e software houses", "description": "Para software houses que revendem o ZP Cobrança aos seus clientes: cadastro da software house e cadastro/alteração dos cedentes (com conta bancária e convênio) da sua rede." }, { "name": "Documentos fiscais", "description": "Consulta das NF-e e CT-e emitidas e recebidas pelo CNPJ da filial (chaves, situação e manifesto), resumo por situação/modal e andamento da captura das NF-e recebidas." }, { "name": "Utilitários", "description": "Teste da credencial, consulta de CEP e de localidade, validação cadastral de CPF/CNPJ e observações livres ligadas a registros." } ], "security": [ { "APP": [], "SENHA": [], "A": [] }, { "REDE": [], "SENHA": [], "A": [] }, { "CNPJ": [], "SENHA": [], "A": [] }, { "CPF": [], "SENHA": [], "A": [] } ], "components": { "securitySchemes": { "APP": { "type": "apiKey", "in": "query", "name": "APP", "description": "Nome do app (perfil App) — use um entre APP, REDE, CNPJ e CPF" }, "REDE": { "type": "apiKey", "in": "query", "name": "REDE", "description": "Nome da rede (perfil Rede)" }, "CNPJ": { "type": "apiKey", "in": "query", "name": "CNPJ", "description": "CNPJ da filial ou do cliente, só números (perfis Filial e Cliente)" }, "CPF": { "type": "apiKey", "in": "query", "name": "CPF", "description": "CPF, só números" }, "SENHA": { "type": "apiKey", "in": "query", "name": "SENHA", "description": "md5(identificador + AAAA-MM-DD + valor de APP/REDE/CNPJ/CPF)" }, "A": { "type": "apiKey", "in": "query", "name": "A", "description": "Id do app no ZP" } }, "schemas": { "Erro": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "errors": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "id_ordem": "Valor inválido" } } } } }, "responses": { "Erro400": { "description": "Dados inválidos ou regra de negócio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "Erro401": { "description": "Identificador, senha ou app inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "example": { "status": "error", "errors": { "error": "Não autorizada!" } } } } }, "Erro403": { "description": "Perfil sem permissão para este método, ou registro fora do escopo do identificador", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "example": { "status": "error", "errors": { "acesso": "Negado" } } } } }, "Erro405": { "description": "Método não implementado neste endpoint" } } }, "paths": { "/v1/terceiro/cobranca": { "get": { "tags": [ "Cobranças" ], "summary": "Consulta uma cobrança ou lista as de um convênio por vencimento", "description": "Rota principal do ZP Cobrança. A cobrança é emitida num convênio (conta bancária + integrador + tipo) do cedente do acesso. Uma cobrança só por chamada: o ZP grava e já registra no banco/integrador na mesma chamada. Várias cobranças: o ZP cria um lote, grava todas na situação NW e o registro no banco é feito depois, pela rotina do ZP (acompanhe por /lote e GET cobranca). Se qualquer cobrança do pedido for recusada na validação, nenhuma é gravada. PUT existe na permissão, mas não está implementado (405). Escopo: o perfil Filial usa os convênios do próprio cedente; os outros perfis informam id_tx_estabelecimento (= id do cedente).\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.\n\n**Ações** (`acao` na query):\n- `get`: Uma cobrança pelo id_cobranca (padrão).\n- `list`: Cobranças do convênio com vencimento entre data_inicial e data_final.", "operationId": "get_cobranca", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_convenio", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Convênio (id_cob_convenio).", "example": 10 }, { "name": "acao", "in": "query", "required": false, "schema": { "type": "string" }, "description": "get (uma cobrança, padrão) ou list (por período de vencimento)." }, { "name": "id_cobranca", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "acao=get: obrigatório. acao=list: não enviar." }, { "name": "data_inicial", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "acao=list: obrigatório; vencimento inicial (AAAA-MM-DD). acao=get: não enviar." }, { "name": "data_final", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "acao=list: obrigatório; vencimento final, maior ou igual à inicial." }, { "name": "id_tx_estabelecimento", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cedente; fixo no perfil Filial." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "cobrancas_sucesso": { "cobrancas": [ { "id_cob_cobranca": 5001, "tipo": "BOLETO", "situacao": "RG", "codigo_cobranca": "PED-1001", "id_cob_convenio": 10, "id_cob_integrador": 3, "id_cob_tipo": 1, "integracao": "", "homologacao": true, "nosso_numero": 123, "documento_especie": "DM", "documento_numero": 1001, "documento_data": "2026-11-12", "documento_valor": 150.0, "documento_vencimento": "2026-12-10", "documento_hora_vencimento": null, "instrucoes": "NÃO RECEBER APÓS 30 DIAS DO VENCIMENTO", "observacoes": "", "perc_multa": 2.0, "perc_juros_dia": 0.033, "perc_desconto1": 0.0, "data_desconto1": null, "perc_desconto2": 0.0, "data_desconto2": null, "perc_desconto3": 0.0, "data_desconto3": null, "prazo_baixa": 0, "prazo_protesto": 0, "linha_digitavel": "99999999999999999999999999999999999999999999999", "codigo_barras": "99999999999999999999999999999999999999999999", "pix_emv": "", "pix_tx_id": "", "token_cartao": "", "identificador_externo": "", "data_hora_processamento": "2026-11-12 10:00:00.000", "data_pagamento": null, "data_credito": null, "valor_recebido": 0.0, "valor_multa": 0.0, "valor_juros": 0.0, "valor_tarifas": 0.0, "response_json_integrador": "", "url_impressao_cobranca": "https://zp1.txfuel.com.br/api/v1/generica/zpCobrancaPdf?cobranca=&cob_tipo=BOLETO", "cedente": { "cpf_cnpj": "11222333000181", "nome_razao_social": "EMPRESA EXEMPLO LTDA", "cep": "80000000", "logradouro": "AVENIDA EXEMPLO", "numero": 1000, "complemento": "SALA 1", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "telefone": "4133330000", "celular": "41988880000", "email": "financeiro@exemplo.com.br" }, "conta": { "banco": "", "agencia": "1234", "agencia_dv": "0", "numero": "56789", "numero_dv": "0" }, "sacado": { "cpf_cnpj": "12345678909", "nome_razao_social": "CLIENTE EXEMPLO DA SILVA", "cep": "80000000", "logradouro": "RUA EXEMPLO", "numero": 100, "complemento": "", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "telefone": "", "celular": "41999990000", "email": "cliente@exemplo.com.br" }, "avalista": { "cpf_cnpj": "", "nome_razao_social": "", "cep": "", "logradouro": "", "numero": 0, "complemento": "", "bairro": "", "localidade": "", "estado": "", "telefone": "", "celular": "", "email": "" } } ], "totalRequestTimeMs": 25, "totalDatabaseTimeMs": 0, "totalGatewayTimeMs": 0, "idLote": 0 } } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "post": { "tags": [ "Cobranças" ], "summary": "Emite uma ou várias cobranças", "description": "Corpo JSON. Datas no formato AAAA-MM-DD. documento_hora_vencimento é aceito mas hoje não é gravado. Regras de CARTAO/PIX: sem multa, juros, descontos, prazos de baixa/protesto e sem avalista. Resposta: com uma cobrança, já registrada (linha digitável, PIX copia e cola, ou pagamento do cartão); com várias, situação NW e idLote preenchido.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "post_cobranca", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_tx_estabelecimento", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cedente (id do cedente = id da filial). Fixo no perfil Filial; nos outros perfis, informe." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id_convenio": { "type": "integer", "description": "Convênio do cedente (id_cob_convenio)." }, "tipo": { "type": "string", "description": "BOLETO, PIX ou CARTAO; tem de ser o tipo do convênio." }, "cobrancas": { "type": "array", "items": { "type": "object", "properties": { "documento_data": { "type": "string", "format": "date", "description": "Data do documento (AAAA-MM-DD)." }, "documento_valor": { "type": "number", "description": "Valor da cobrança. Maior que zero e não menor que o valor mínimo do convênio." }, "documento_vencimento": { "type": "string", "format": "date", "description": "Vencimento (AAAA-MM-DD); não pode ser anterior a hoje." }, "documento_numero": { "type": "integer", "description": "Número do documento (seu controle)." }, "documento_especie": { "type": "string", "description": "Espécie do documento do boleto, até 2 letras (ex.: DM)." }, "codigo_cobranca": { "type": "string", "description": "Código livre seu para identificar a cobrança (volta na consulta)." }, "nosso_numero": { "type": "integer", "description": "Nosso número do boleto. Ausente ou 0: o ZP usa o próximo do convênio. Repetir um nosso número do mesmo convênio dá erro." }, "instrucoes": { "type": "string", "description": "Instruções do boleto." }, "observacoes": { "type": "string", "description": "Observações." }, "incluir_pix_boleto": { "type": "boolean", "description": "Boleto: incluir QR Code PIX no boleto (padrão false)." }, "card_token": { "type": "string", "description": "CARTAO: obrigatório; card_token de um cartão cadastrado em /cartao para o cedente do convênio. Proibido nos outros tipos." }, "perc_multa": { "type": "number", "description": "Boleto: % de multa (>= 0). Proibido em PIX/CARTAO." }, "perc_juros_dia": { "type": "number", "description": "Boleto: % de juros ao dia (>= 0). Proibido em PIX/CARTAO." }, "perc_desconto1": { "type": "number", "description": "Boleto: % do desconto 1; exige data_desconto1. Proibido em PIX/CARTAO." }, "data_desconto1": { "type": "string", "format": "date", "description": "Boleto: data limite do desconto 1 (até o vencimento); exige perc_desconto1." }, "perc_desconto2": { "type": "number", "description": "Boleto: % do desconto 2; só com o desconto 1 preenchido." }, "data_desconto2": { "type": "string", "format": "date", "description": "Boleto: data do desconto 2, depois da data do desconto 1 e até o vencimento." }, "perc_desconto3": { "type": "number", "description": "Boleto: % do desconto 3; só com o desconto 2 preenchido." }, "data_desconto3": { "type": "string", "format": "date", "description": "Boleto: data do desconto 3, depois da data do desconto 2 e até o vencimento." }, "prazo_baixa": { "type": "integer", "description": "Boleto: dias para baixa (>= 0). Proibido em PIX/CARTAO." }, "prazo_protesto": { "type": "integer", "description": "Boleto: dias para protesto (>= 0). Proibido em PIX/CARTAO." }, "sacado": { "type": "object", "description": "Pagador.", "properties": { "cpf_cnpj": { "type": "string", "description": "CPF ou CNPJ do pagador, só números (validado). Não pode ser igual ao do cedente nem ao do avalista." }, "nome_razao_social": { "type": "string", "description": "Nome ou razão social." }, "cep": { "type": "string", "description": "CEP, 8 dígitos." }, "logradouro": { "type": "string", "description": "Logradouro." }, "numero": { "type": "integer", "description": "Número. Obrigatório o número OU o complemento." }, "complemento": { "type": "string", "description": "Complemento. Obrigatório o número OU o complemento." }, "bairro": { "type": "string", "description": "Bairro." }, "localidade": { "type": "string", "description": "Cidade." }, "estado": { "type": "string", "description": "UF, 2 letras." }, "telefone": { "type": "string", "description": "Telefone fixo com DDD, só números (validado quando informado)." }, "celular": { "type": "string", "description": "Celular com DDD, só números (validado)." }, "email": { "type": "string", "description": "E-mail." } } }, "avalista": { "type": "object", "description": "Sacador/avalista (só BOLETO).", "properties": { "cpf_cnpj": { "type": "string", "description": "CPF ou CNPJ do avalista. Sem ele, nenhum outro campo do avalista pode ser enviado. Com ele, valem as mesmas regras do sacado (nome, CEP, logradouro, número ou complemento, bairro, cidade, UF, celular e e-mail obrigatórios)." }, "nome_razao_social": { "type": "string", "description": "Nome ou razão social." }, "cep": { "type": "string", "description": "CEP, 8 dígitos." }, "logradouro": { "type": "string", "description": "Logradouro." }, "numero": { "type": "integer", "description": "Número. Obrigatório o número OU o complemento." }, "complemento": { "type": "string", "description": "Complemento. Obrigatório o número OU o complemento." }, "bairro": { "type": "string", "description": "Bairro." }, "localidade": { "type": "string", "description": "Cidade." }, "estado": { "type": "string", "description": "UF, 2 letras." }, "telefone": { "type": "string", "description": "Telefone fixo com DDD, só números (validado quando informado)." }, "celular": { "type": "string", "description": "Celular com DDD, só números (validado)." }, "email": { "type": "string", "description": "E-mail." } } } } }, "description": "Uma ou mais cobranças." } }, "required": [ "id_convenio", "tipo", "cobrancas" ] }, "example": { "id_convenio": 10, "tipo": "BOLETO", "cobrancas": [ { "codigo_cobranca": "PED-1001", "documento_numero": 1001, "documento_data": "2026-11-12", "documento_valor": 150.0, "documento_vencimento": "2026-12-10", "documento_especie": "DM", "instrucoes": "NÃO RECEBER APÓS 30 DIAS DO VENCIMENTO", "perc_multa": 2.0, "perc_juros_dia": 0.033, "incluir_pix_boleto": true, "sacado": { "cpf_cnpj": "12345678909", "nome_razao_social": "CLIENTE EXEMPLO DA SILVA", "cep": "80000000", "logradouro": "RUA EXEMPLO", "numero": 100, "complemento": "", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "telefone": "", "celular": "41999990000", "email": "cliente@exemplo.com.br" } } ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "cobrancas_sucesso": { "cobrancas": [ { "id_cob_cobranca": 5001, "tipo": "BOLETO", "situacao": "RG", "codigo_cobranca": "PED-1001", "id_cob_convenio": 10, "id_cob_integrador": 3, "id_cob_tipo": 1, "integracao": "", "homologacao": true, "nosso_numero": 123, "documento_especie": "DM", "documento_numero": 1001, "documento_data": "2026-11-12", "documento_valor": 150.0, "documento_vencimento": "2026-12-10", "documento_hora_vencimento": null, "instrucoes": "NÃO RECEBER APÓS 30 DIAS DO VENCIMENTO", "observacoes": "", "perc_multa": 2.0, "perc_juros_dia": 0.033, "perc_desconto1": 0.0, "data_desconto1": null, "perc_desconto2": 0.0, "data_desconto2": null, "perc_desconto3": 0.0, "data_desconto3": null, "prazo_baixa": 0, "prazo_protesto": 0, "linha_digitavel": "99999999999999999999999999999999999999999999999", "codigo_barras": "99999999999999999999999999999999999999999999", "pix_emv": "", "pix_tx_id": "", "token_cartao": "", "identificador_externo": "", "data_hora_processamento": "2026-11-12 10:00:00.000", "data_pagamento": null, "data_credito": null, "valor_recebido": 0.0, "valor_multa": 0.0, "valor_juros": 0.0, "valor_tarifas": 0.0, "response_json_integrador": "", "url_impressao_cobranca": "https://zp1.txfuel.com.br/api/v1/generica/zpCobrancaPdf?cobranca=&cob_tipo=BOLETO", "cedente": { "cpf_cnpj": "11222333000181", "nome_razao_social": "EMPRESA EXEMPLO LTDA", "cep": "80000000", "logradouro": "AVENIDA EXEMPLO", "numero": 1000, "complemento": "SALA 1", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "telefone": "4133330000", "celular": "41988880000", "email": "financeiro@exemplo.com.br" }, "conta": { "banco": "", "agencia": "1234", "agencia_dv": "0", "numero": "56789", "numero_dv": "0" }, "sacado": { "cpf_cnpj": "12345678909", "nome_razao_social": "CLIENTE EXEMPLO DA SILVA", "cep": "80000000", "logradouro": "RUA EXEMPLO", "numero": 100, "complemento": "", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "telefone": "", "celular": "41999990000", "email": "cliente@exemplo.com.br" }, "avalista": { "cpf_cnpj": "", "nome_razao_social": "", "cep": "", "logradouro": "", "numero": 0, "complemento": "", "bairro": "", "localidade": "", "estado": "", "telefone": "", "celular": "", "email": "" } } ], "totalRequestTimeMs": 850, "totalDatabaseTimeMs": 40, "totalGatewayTimeMs": 800, "idLote": 0 } } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "delete": { "tags": [ "Cobranças" ], "summary": "Cancela uma cobrança", "description": "Não cancela no banco na mesma chamada: cobrança nova (NW) vira CS; registrada ou paga vira FC e a rotina do ZP faz o cancelamento. Acompanhe pelo GET.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "delete_cobranca", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_cobranca", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Cobrança (id_cob_cobranca).", "example": 5001 }, { "name": "id_tx_estabelecimento", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cedente; fixo no perfil Filial." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "cobrancas_sucesso": { "cobrancas": [ { "id_cob_cobranca": 5001, "situacao": "FC", "...": "(demais campos da cobrança)" } ], "totalRequestTimeMs": 12, "totalDatabaseTimeMs": 12, "totalGatewayTimeMs": 0, "idLote": 0 } } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/lote": { "get": { "tags": [ "Cobranças" ], "summary": "Um lote ou lista de lotes de um convênio", "description": "Mostra quantas cobranças de cada lote (criado pelo POST cobranca com mais de uma cobrança) já foram processadas pela rotina do ZP. Só GET. Atenção: a rota não confere se o convênio é do acesso (ver dúvidas no relatório).\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.\n\n**Ações** (`acao` na query):\n- `get`: Um lote (padrão).\n- `list`: Lotes do convênio criados no período, paginados.", "operationId": "get_lote", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_cob_convenio", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Convênio dos lotes.", "example": 10 }, { "name": "acao", "in": "query", "required": false, "schema": { "type": "string" }, "description": "get (um lote, padrão) ou list." }, { "name": "id_cob_lote", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "acao=get: obrigatório." }, { "name": "data_inicial", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "acao=list: data de criação inicial (padrão 1980-01-01). Aceita também data_inicio e data_ini." }, { "name": "data_final", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "acao=list: data de criação final (padrão 2099-12-31). Aceita também data_fim." }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "acao=list: tamanho da página, de 1 a 50." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "acao=list: página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "id_cob_lote": 77, "total_cobrancas": 120, "cobrancas_processadas": 118, "cobrancas_pendentes": 2, "lote_processado": "N" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/cartao": { "get": { "tags": [ "Cobranças" ], "summary": "Lista os cartões do cedente ou consulta um", "description": "acao=get devolve os campos do cartão na raiz (sem a lista cartoes).\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.\n\n**Ações** (`acao` na query):\n- `list`: Cartões ativos do cedente (padrão).\n- `get`: Um cartão por id_cob_cartao ou card_token.", "operationId": "get_cartao", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_cob_cedente", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Cedente.", "example": 25 }, { "name": "acao", "in": "query", "required": false, "schema": { "type": "string" }, "description": "list (padrão) ou get." }, { "name": "id_cob_cartao", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "acao=get: id do cartão (ou use card_token)." }, { "name": "card_token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "acao=get: token do cartão (ou use id_cob_cartao)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "cartoes": [ { "id_cob_cartao": 300, "id_cob_cedente": 25, "card_token": "0123456789abcdef0123456789abcdef", "card_numero": "4111 **** **** 1111", "card_bandeira": "VISA", "card_nome_titular": "CLIENTE EXEMPLO", "card_cpf_cnpj_titular": "12345678909", "card_mes_vencimento": "12", "card_ano_vencimento": "2030", "card_cep_cobranca": "80000000", "card_apelido": "CARTAO EMPRESA", "pag_nome_razao_social": "CLIENTE EXEMPLO DA SILVA", "pag_cpf_cnpj": "12345678909", "pag_cep": "80000000", "pag_numero": 100, "pag_complemento": "", "pag_bairro": "CENTRO", "pag_localidade": "CURITIBA", "pag_estado": "PR", "pag_telefone": "", "pag_celular": "41999990000", "pag_email": "cliente@exemplo.com.br", "data_hora_criacao": "2026-11-12T10:00:00" } ] } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "post": { "tags": [ "Cobranças" ], "summary": "Cadastra um cartão", "description": "Corpo JSON.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "post_cartao", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id_cob_cedente": { "type": "integer", "description": "Cedente dono do cartão (o do acesso)." }, "pag_nome_razao_social": { "type": "string", "description": "Nome do pagador." }, "pag_cpf_cnpj": { "type": "string", "description": "CPF/CNPJ do pagador, só números." }, "pag_cep": { "type": "string", "description": "CEP, 8 dígitos." }, "pag_logradouro": { "type": "string", "description": "Logradouro." }, "pag_numero": { "type": "integer", "description": "Número. Obrigatório o número OU o complemento." }, "pag_complemento": { "type": "string", "description": "Complemento." }, "pag_bairro": { "type": "string", "description": "Bairro." }, "pag_localidade": { "type": "string", "description": "Cidade." }, "pag_estado": { "type": "string", "description": "UF." }, "pag_telefone": { "type": "string", "description": "Telefone fixo com DDD (validado quando informado)." }, "pag_celular": { "type": "string", "description": "Celular com DDD." }, "pag_email": { "type": "string", "description": "E-mail." }, "card_numero": { "type": "string", "description": "Número do cartão (só os dígitos são usados)." }, "card_cvv": { "type": "string", "description": "Código de segurança." }, "card_mes_vencimento": { "type": "string", "description": "Mês, 2 dígitos." }, "card_ano_vencimento": { "type": "string", "description": "Ano, 4 dígitos." }, "card_nome_titular": { "type": "string", "description": "Nome impresso no cartão." }, "card_cpf_cnpj_titular": { "type": "string", "description": "CPF/CNPJ do titular." }, "card_cep_cobranca": { "type": "string", "description": "CEP de cobrança do cartão (validado quando informado)." }, "card_apelido": { "type": "string", "description": "Apelido para identificar o cartão." } }, "required": [ "id_cob_cedente", "pag_nome_razao_social", "pag_cpf_cnpj", "pag_cep", "pag_logradouro", "pag_bairro", "pag_localidade", "pag_estado", "pag_celular", "pag_email", "card_numero", "card_cvv", "card_mes_vencimento", "card_ano_vencimento", "card_nome_titular", "card_cpf_cnpj_titular" ] }, "example": { "id_cob_cedente": 25, "pag_nome_razao_social": "CLIENTE EXEMPLO DA SILVA", "pag_cpf_cnpj": "12345678909", "pag_cep": "80000000", "pag_logradouro": "RUA EXEMPLO", "pag_numero": 100, "pag_bairro": "CENTRO", "pag_localidade": "CURITIBA", "pag_estado": "PR", "pag_celular": "41999990000", "pag_email": "cliente@exemplo.com.br", "card_numero": "4111111111111111", "card_cvv": "123", "card_mes_vencimento": "12", "card_ano_vencimento": "2030", "card_nome_titular": "CLIENTE EXEMPLO", "card_cpf_cnpj_titular": "12345678909", "card_apelido": "CARTAO EMPRESA" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "id_cob_cartao": 300, "id_cob_cedente": 25, "card_token": "0123456789abcdef0123456789abcdef", "card_numero": "4111 **** **** 1111", "card_bandeira": "VISA", "card_nome_titular": "CLIENTE EXEMPLO", "card_cpf_cnpj_titular": "12345678909", "card_mes_vencimento": "12", "card_ano_vencimento": "2030", "card_cep_cobranca": "80000000", "card_apelido": "CARTAO EMPRESA", "pag_nome_razao_social": "CLIENTE EXEMPLO DA SILVA", "pag_cpf_cnpj": "12345678909", "pag_cep": "80000000", "pag_numero": 100, "pag_complemento": "", "pag_bairro": "CENTRO", "pag_localidade": "CURITIBA", "pag_estado": "PR", "pag_telefone": "", "pag_celular": "41999990000", "pag_email": "cliente@exemplo.com.br", "data_hora_criacao": "2026-11-12T10:00:00" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "put": { "tags": [ "Cobranças" ], "summary": "Altera titular e apelido de um cartão", "description": "Só titular, CPF/CNPJ do titular e apelido mudam; os campos não enviados ficam vazios. O ZP desativa o registro antigo e cria outro com o mesmo card_token: o id_cob_cartao muda (use o da resposta).\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "put_cartao", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_cob_cartao", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cartão (ou use card_token).", "example": 300 }, { "name": "card_token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Token do cartão (ou use id_cob_cartao)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "card_nome_titular": { "type": "string", "description": "Nome do titular (sem ele a gravação é recusada)." }, "card_cpf_cnpj_titular": { "type": "string", "description": "CPF/CNPJ do titular (validado)." }, "card_apelido": { "type": "string", "description": "Apelido; ausente = fica vazio." } }, "required": [ "card_nome_titular", "card_cpf_cnpj_titular" ] }, "example": { "card_nome_titular": "CLIENTE EXEMPLO", "card_cpf_cnpj_titular": "12345678909", "card_apelido": "CARTAO NOVO" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "id_cob_cartao": 300, "id_cob_cedente": 25, "card_token": "0123456789abcdef0123456789abcdef", "card_numero": "4111 **** **** 1111", "card_bandeira": "VISA", "card_nome_titular": "CLIENTE EXEMPLO", "card_cpf_cnpj_titular": "12345678909", "card_mes_vencimento": "12", "card_ano_vencimento": "2030", "card_cep_cobranca": "80000000", "card_apelido": "CARTAO EMPRESA", "pag_nome_razao_social": "CLIENTE EXEMPLO DA SILVA", "pag_cpf_cnpj": "12345678909", "pag_cep": "80000000", "pag_numero": 100, "pag_complemento": "", "pag_bairro": "CENTRO", "pag_localidade": "CURITIBA", "pag_estado": "PR", "pag_telefone": "", "pag_celular": "41999990000", "pag_email": "cliente@exemplo.com.br", "data_hora_criacao": "2026-11-12T10:00:00" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "delete": { "tags": [ "Cobranças" ], "summary": "Desativa um cartão", "description": "Desativa (ativo = N); o cartão deixa de aparecer e o token deixa de valer para novas cobranças.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "delete_cartao", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_cob_cartao", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cartão (ou use card_token).", "example": 300 }, { "name": "card_token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Token do cartão (ou use id_cob_cartao)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/cedente": { "get": { "tags": [ "Cedentes e software houses" ], "summary": "Consulta um cedente com contas e convênios", "description": "Para software houses (rede no ZP) que cadastram os próprios clientes como cedentes. Só os perfis Rede (a rede da software house) e Filial (a filial da própria software house) usam; os demais recebem 403. O POST cria, numa transação, o cedente (com a pessoa, a filial e o acesso de terceiro do cedente), uma conta bancária e um convênio, e devolve os ids e o identificador do acesso do cedente. Não há DELETE. Os ids de banco, integrador e tipo de cobrança são fornecidos pela TX Fuel.\n\n**Perfis**: App, Rede, Estabelecimento.", "operationId": "get_cedente", "x-perfis": [ "app", "rede", "estabelecimento" ], "parameters": [ { "name": "id_cob_cedente", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Cedente da rede da software house.", "example": 25 } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "dados_integracao": { "id_cob_cedente": 25, "identificador_terceiro": "" }, "cedente": { "id_cob_cedente": 25, "cpf_cnpj": "11222333000181", "nome_razao_social": "EMPRESA EXEMPLO LTDA", "cep": "80000000", "logradouro": "AVENIDA EXEMPLO", "numero": 1000, "complemento": "SALA 1", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "celular": "41988880000", "email": "financeiro@exemplo.com.br", "telefone": "", "ativo": "S" }, "contas": [ { "id_cob_conta": 40, "id_cob_cedente": 25, "id_cob_banco": 1, "descricao": "CONTA PRINCIPAL", "agencia": "1234", "agencia_dv": "0", "numero": "56789", "numero_dv": "0", "ativo": "S", "convenios": [ { "id_cob_convenio": 10, "id_cob_conta": 40, "descricao": "BOLETO CONTA PRINCIPAL", "valor_minimo": 0.01, "homologacao": "S", "id_cob_integrador": 3, "id_cob_tipo": 1, "webhook_url": "https://sistema.exemplo.com.br/webhook/zp", "webhook_header": "", "validade": "2099-12-31", "val1": "", "val2": "", "val3": "", "...": "(val4 a val10)", "ativo": "S" } ] } ] } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "post": { "tags": [ "Cedentes e software houses" ], "summary": "Cria cedente, conta e convênio", "description": "Corpo JSON. Os ids (id_cob_cedente, id_cob_conta, id_cob_convenio, id_tx_pessoa) enviados no corpo são ignorados: sempre cria registros novos.\n\n**Perfis**: App, Rede, Estabelecimento.", "operationId": "post_cedente", "x-perfis": [ "app", "rede", "estabelecimento" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cedente": { "type": "object", "description": "Dados do cedente.", "properties": { "cpf_cnpj": { "type": "string", "description": "CPF/CNPJ do cedente (só na criação)." }, "nome_razao_social": { "type": "string", "description": "Nome ou razão social." }, "cep": { "type": "string", "description": "CEP." }, "logradouro": { "type": "string", "description": "Até 50 caracteres." }, "numero": { "type": "integer", "description": "Número." }, "complemento": { "type": "string", "description": "Até 20 caracteres." }, "bairro": { "type": "string", "description": "Até 50 caracteres." }, "localidade": { "type": "string", "description": "Cidade, até 50 caracteres." }, "estado": { "type": "string", "description": "UF." }, "telefone": { "type": "string", "description": "Telefone fixo com DDD (validado quando informado)." }, "celular": { "type": "string", "description": "Celular com DDD." }, "email": { "type": "string", "description": "E-mail." }, "ativo": { "type": "string", "description": "S ou N." } } }, "conta": { "type": "object", "description": "Conta bancária.", "properties": { "id_cob_banco": { "type": "integer", "description": "Banco — id fornecido pela TX Fuel." }, "descricao": { "type": "string", "description": "Até 50 caracteres." }, "agencia": { "type": "string", "description": "Agência." }, "agencia_dv": { "type": "string", "description": "Dígito da agência (1 caractere)." }, "numero": { "type": "string", "description": "Número da conta." }, "numero_dv": { "type": "string", "description": "Dígito da conta (1 caractere)." }, "ativo": { "type": "string", "description": "S ou N." } } }, "convenio": { "type": "object", "description": "Convênio de cobrança da conta.", "properties": { "id_cob_integrador": { "type": "integer", "description": "Integrador (banco/gateway) do convênio — id fornecido pela TX Fuel." }, "id_cob_tipo": { "type": "integer", "description": "Tipo de cobrança do convênio (BOLETO, PIX ou CARTAO) — id fornecido pela TX Fuel." }, "descricao": { "type": "string", "description": "Descrição, até 50 caracteres." }, "valor_minimo": { "type": "number", "description": "Valor mínimo de cobrança (padrão 0,01)." }, "homologacao": { "type": "string", "description": "S (padrão, homologação/teste) ou N (produção)." }, "validade": { "type": "string", "format": "date", "description": "Validade do convênio (padrão 2099-12-31)." }, "webhook_url": { "type": "string", "description": "URL para receber os avisos de mudança das cobranças." }, "webhook_header": { "type": "string", "description": "Cabeçalho enviado no webhook (ex.: autorização)." }, "val1 … val10": { "type": "string", "description": "Parâmetros do integrador (credenciais, carteira, número do convênio…), conforme o integrador. Podem vir também dentro de \"parametros\": {\"val1\": …}." }, "ativo": { "type": "string", "description": "S ou N." } } } }, "required": [ "cedente", "conta", "convenio" ] }, "example": { "cedente": { "cpf_cnpj": "11222333000181", "nome_razao_social": "EMPRESA EXEMPLO LTDA", "cep": "80000000", "logradouro": "AVENIDA EXEMPLO", "numero": 1000, "complemento": "SALA 1", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "celular": "41988880000", "email": "financeiro@exemplo.com.br" }, "conta": { "id_cob_banco": 1, "descricao": "CONTA PRINCIPAL", "agencia": "1234", "agencia_dv": "0", "numero": "56789", "numero_dv": "0" }, "convenio": { "id_cob_integrador": 3, "id_cob_tipo": 1, "descricao": "BOLETO CONTA PRINCIPAL", "homologacao": "S", "webhook_url": "https://sistema.exemplo.com.br/webhook/zp", "parametros": { "val1": "", "val2": "" } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "dados_integracao": { "id_cob_cedente": 25, "id_cob_conta": 40, "id_cob_convenio": 10, "identificador_terceiro": "" } } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "put": { "tags": [ "Cedentes e software houses" ], "summary": "Altera cedente, contas e convênios (parcial)", "description": "Corpo JSON; só os blocos e campos enviados mudam. Tudo numa transação: se um bloco falhar, nada é gravado.\n\n**Perfis**: App, Rede, Estabelecimento.", "operationId": "put_cedente", "x-perfis": [ "app", "rede", "estabelecimento" ], "parameters": [ { "name": "id_cob_cedente", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Cedente (só na URL).", "example": 25 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cedente": { "type": "object", "description": "Campos a alterar do cedente (cpf_cnpj não muda).", "properties": { "cpf_cnpj": { "type": "string", "description": "CPF/CNPJ do cedente (só na criação)." }, "nome_razao_social": { "type": "string", "description": "Nome ou razão social." }, "cep": { "type": "string", "description": "CEP." }, "logradouro": { "type": "string", "description": "Até 50 caracteres." }, "numero": { "type": "integer", "description": "Número." }, "complemento": { "type": "string", "description": "Até 20 caracteres." }, "bairro": { "type": "string", "description": "Até 50 caracteres." }, "localidade": { "type": "string", "description": "Cidade, até 50 caracteres." }, "estado": { "type": "string", "description": "UF." }, "telefone": { "type": "string", "description": "Telefone fixo com DDD (validado quando informado)." }, "celular": { "type": "string", "description": "Celular com DDD." }, "email": { "type": "string", "description": "E-mail." }, "ativo": { "type": "string", "description": "S ou N." } } }, "conta": { "type": "object", "description": "Uma conta a alterar: id_cob_conta obrigatório + campos.", "properties": { "id_cob_conta": { "type": "integer", "description": "Conta do cedente." }, "id_cob_banco": { "type": "integer", "description": "Banco — id fornecido pela TX Fuel." }, "descricao": { "type": "string", "description": "Até 50 caracteres." }, "agencia": { "type": "string", "description": "Agência." }, "agencia_dv": { "type": "string", "description": "Dígito da agência (1 caractere)." }, "numero": { "type": "string", "description": "Número da conta." }, "numero_dv": { "type": "string", "description": "Dígito da conta (1 caractere)." }, "ativo": { "type": "string", "description": "S ou N." } } }, "contas": { "type": "array", "items": {}, "description": "Várias contas: cada uma com id_cob_conta, campos e opcionalmente convenios[] (cada um com id_cob_convenio)." }, "convenio": { "type": "object", "description": "Um convênio a alterar: id_cob_convenio obrigatório + campos (se vier conta, tem de ser dessa conta).", "properties": { "id_cob_convenio": { "type": "integer", "description": "Convênio do cedente." }, "id_cob_integrador": { "type": "integer", "description": "Integrador (banco/gateway) do convênio — id fornecido pela TX Fuel." }, "id_cob_tipo": { "type": "integer", "description": "Tipo de cobrança do convênio (BOLETO, PIX ou CARTAO) — id fornecido pela TX Fuel." }, "descricao": { "type": "string", "description": "Descrição, até 50 caracteres." }, "valor_minimo": { "type": "number", "description": "Valor mínimo de cobrança (padrão 0,01)." }, "homologacao": { "type": "string", "description": "S (padrão, homologação/teste) ou N (produção)." }, "validade": { "type": "string", "format": "date", "description": "Validade do convênio (padrão 2099-12-31)." }, "webhook_url": { "type": "string", "description": "URL para receber os avisos de mudança das cobranças." }, "webhook_header": { "type": "string", "description": "Cabeçalho enviado no webhook (ex.: autorização)." }, "val1 … val10": { "type": "string", "description": "Parâmetros do integrador (credenciais, carteira, número do convênio…), conforme o integrador. Podem vir também dentro de \"parametros\": {\"val1\": …}." }, "ativo": { "type": "string", "description": "S ou N." } } } } }, "example": { "convenio": { "id_cob_convenio": 10, "homologacao": "N" } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "dados_integracao": { "id_cob_cedente": 25, "identificador_terceiro": "" }, "cedente": { "id_cob_cedente": 25, "cpf_cnpj": "11222333000181", "nome_razao_social": "EMPRESA EXEMPLO LTDA", "cep": "80000000", "logradouro": "AVENIDA EXEMPLO", "numero": 1000, "complemento": "SALA 1", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "celular": "41988880000", "email": "financeiro@exemplo.com.br", "telefone": "", "ativo": "S" }, "contas": [ { "id_cob_conta": 40, "id_cob_cedente": 25, "id_cob_banco": 1, "descricao": "CONTA PRINCIPAL", "agencia": "1234", "agencia_dv": "0", "numero": "56789", "numero_dv": "0", "ativo": "S", "convenios": [ { "id_cob_convenio": 10, "id_cob_conta": 40, "descricao": "BOLETO CONTA PRINCIPAL", "valor_minimo": 0.01, "homologacao": "S", "id_cob_integrador": 3, "id_cob_tipo": 1, "webhook_url": "https://sistema.exemplo.com.br/webhook/zp", "webhook_header": "", "validade": "2099-12-31", "val1": "", "val2": "", "val3": "", "...": "(val4 a val10)", "ativo": "S" } ] } ] } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/softwareHouse": { "post": { "tags": [ "Cedentes e software houses" ], "summary": "Cadastra a software house e o usuário responsável", "description": "Em qualquer erro nada é gravado. A resposta de sucesso não traz ids nem credenciais: elas vão por e-mail.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "post_softwareHouse", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "cnpj_software_house", "in": "query", "required": true, "schema": { "type": "string" }, "description": "CNPJ da software house, só números.", "example": "11222333000181" }, { "name": "id_plano", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Plano contratado — id fornecido pela TX Fuel.", "example": 1 }, { "name": "cpf", "in": "query", "required": true, "schema": { "type": "string" }, "description": "CPF do responsável (vira o login), só números.", "example": "12345678909" }, { "name": "nome", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Nome do responsável.", "example": "RESPONSAVEL EXEMPLO" }, { "name": "celular", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Celular do responsável com DDD.", "example": "41999990000" }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string" }, "description": "E-mail do responsável (recebe as boas-vindas).", "example": "responsavel@exemplo.com.br" }, { "name": "senha_usuario", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Senha inicial do responsável.", "example": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/nfeChave": { "get": { "tags": [ "Documentos fiscais" ], "summary": "Lista de NF-e", "description": "Lista as NF-e capturadas para o CNPJ da filial (como emitente ou destinatário), com situação, manifesto e modal. Só GET. A lista não é paginada.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_nfeChave", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_tx_estabelecimento", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filial cujo CNPJ (parâmetro CNPJ_NFE) é consultado. Fixo no perfil Filial; nos outros perfis, informe." }, { "name": "data_inicial", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial: vale a data de emissão OU a data de cadastro no ZP (AAAA-MM-DD; aceita também data_inicio e data_ini)." }, { "name": "data_final", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final (AAAA-MM-DD; aceita também data_fim)." }, { "name": "chave", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Chave de acesso (44 dígitos); * ou ausente = todas." }, { "name": "situacao", "in": "query", "required": false, "schema": { "type": "string" }, "description": "AUTORIZADA, CANCELADA…; * = todas." }, { "name": "manifesto", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CONFIRMADA, CIÊNCIA, DESCONHECIDA, NÃO REALIZADA; * = todos." }, { "name": "modal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "RODOVIÁRIO, FERROVIÁRIO, AEROVIÁRIO, DUTOVIÁRIO, HIDROVIÁRIO; * = todos." }, { "name": "xml", "in": "query", "required": false, "schema": { "type": "string" }, "description": "S = só as que já têm XML; N = sem XML; * = todas." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "data": [ { "chave": "41261111222333000181550010000012341000012345", "numero": 1234, "serie": 1, "emit_cnpj": "11222333000181", "dest_cnpj": "44555666000199", "data_emissao": "2026-11-10", "xml": "S", "situacao": "AUTORIZADA", "manifesto": "CIÊNCIA", "modal": "RODOVIÁRIO" } ] } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/nfeResumo": { "get": { "tags": [ "Documentos fiscais" ], "summary": "Totais do período", "description": "Contagens das NF-e de saída (emitidas pelo CNPJ da filial) e de entrada (recebidas) no período de emissão. Só GET.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_nfeResumo", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_tx_estabelecimento", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filial cujo CNPJ (parâmetro CNPJ_NFE) é consultado. Fixo no perfil Filial; nos outros perfis, informe." }, { "name": "data_inicial", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Emissão inicial (AAAA-MM-DD)." }, { "name": "data_final", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Emissão final (AAAA-MM-DD)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "data": [ { "total_notas_de_saida": 120, "total_notas_de_entrada": 340, "notas_de_saida_autorizada": 118, "notas_de_entrada_autorizada": 335, "notas_de_saida_cancelada": 2, "notas_de_entrada_cancelada": 5, "notas_de_entrada_confirmada": 300, "notas_de_entrada_ciencia": 30, "...": "(demais contagens)" } ] } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/nfeRecebidaStatus": { "get": { "tags": [ "Documentos fiscais" ], "summary": "Totais e percentuais", "description": "Percentual das NF-e recebidas pelo CNPJ da filial que já têm XML, JSON, PDF e manifesto confirmado no ZP. Sem filtro de data. Só GET.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_nfeRecebidaStatus", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_tx_estabelecimento", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filial cujo CNPJ (parâmetro CNPJ_NFE) é consultado. Fixo no perfil Filial; nos outros perfis, informe." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "recebida_status": { "total": 340, "xml": 330, "perc_xml": 97.1, "json": 330, "perc_json": 97.1, "pdf": 300, "perc_pdf": 88.2, "confirmada": 300, "perc_confirmada": 88.2 } } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/cteChave": { "get": { "tags": [ "Documentos fiscais" ], "summary": "Lista de CT-e", "description": "Lista os CT-e capturados para o CNPJ da filial (como interessado ou emitente), por data de emissão. Só GET. A lista não é paginada.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_cteChave", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_tx_estabelecimento", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filial cujo CNPJ (parâmetro CNPJ_NFE) é consultado. Fixo no perfil Filial; nos outros perfis, informe." }, { "name": "data_inicial", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Emissão inicial (AAAA-MM-DD; aceita também data_inicio e data_ini)." }, { "name": "data_final", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Emissão final (AAAA-MM-DD; aceita também data_fim)." }, { "name": "chave", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Chave de acesso; * ou ausente = todas." }, { "name": "situacao", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Situação; * = todas." }, { "name": "manifesto", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Manifesto; * = todos." }, { "name": "xml", "in": "query", "required": false, "schema": { "type": "string" }, "description": "S = com XML; N = sem; * = todos." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "data": [ { "key": "41261111222333000181570010000004561000004567", "cnpj": "11222333000181", "id": "", "mod": "57", "environment": "", "serie": "1", "cnpj_emitter": "44555666000199", "razao_social": "TRANSPORTADORA EXEMPLO LTDA", "cnpj_addressee": "11222333000181", "date_emission": "2026-11-10", "number": 456, "value": 1500.0, "situacao": "AUTORIZADA", "manifesto": "-", "tomador": "", "xml": "S" } ] } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/status": { "get": { "tags": [ "Utilitários" ], "summary": "Responde ok se a credencial é válida", "description": "Não consulta nada: só confirma que a autenticação (APP/REDE/CNPJ/CPF + SENHA + A) e a permissão do terceiro estão corretas. Útil para testar a conexão da integração. Vale para todos os perfis.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_status", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/consultarCep": { "get": { "tags": [ "Utilitários" ], "summary": "Endereço do CEP", "description": "Consulta o CEP na base do ZP (atualizada por serviço externo quando preciso). Só GET.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_consultarCep", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "cep", "in": "query", "required": true, "schema": { "type": "string" }, "description": "CEP, 8 dígitos (pontuação é ignorada).", "example": "80000000" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "cep": "80000000", "cliente": "", "logradouro": "RUA EXEMPLO", "complemento": "", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "codigo_ibge": "4106902" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/localizarLocalidade": { "get": { "tags": [ "Utilitários" ], "summary": "Cidades", "description": "Até 10 cidades cujo nome contém o texto (sem acentos). Só GET.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_localizarLocalidade", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Parte do nome da cidade.", "example": "curitiba" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "data": [ { "value": "CURITIBA;PR;4106902", "text": "CURITIBA/PR" } ] } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/validarPessoaFisica": { "get": { "tags": [ "Utilitários" ], "summary": "Semelhança dos dados com o bureau", "description": "Compara os dados informados com a base do bureau e devolve o grau de semelhança de cada bloco, a situação do CPF e se há indicação de óbito. Cada chamada consulta o bureau (serviço pago) e fica registrada. Só GET. Os parâmetros vão na query (ou no corpo como application/x-www-form-urlencoded); corpo JSON não é lido.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_validarPessoaFisica", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "documento", "in": "query", "required": true, "schema": { "type": "string" }, "description": "CPF.", "example": "12345678909" }, { "name": "nome", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome completo." }, { "name": "data_nascimento", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "AAAA-MM-DD." }, { "name": "nome_mae", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome da mãe." }, { "name": "cep", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CEP informado pelo cliente." }, { "name": "logradouro", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "numero", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "complemento", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "bairro", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "localidade", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cidade." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "UF." }, { "name": "telefone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Com DDD." }, { "name": "celular", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Com DDD." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "documento": "12345678909", "dados_basicos": 0.95, "endereco": 0.8, "telefone": 0.0, "celular": 1.0, "email": 1.0, "cpf_status": "REGULAR", "falecida": false, "pergunta1": { "Quais destes e-mails você reconhece?": [ { "0": "Nenhum" }, { "1": "cliente@exemplo.com.br" }, { "2": "cliente123@exemplo.com" } ] }, "pergunta2": { "Quais destes telefones você reconhece?": [ { "0": "Nenhum" }, { "1": "…" } ] }, "pergunta3": { "Quais destes endereços você reconhece?": [ { "0": "Nenhum" }, { "1": "…" } ] }, "token": "0123456789abcdef0123456789abcdef" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/validarPessoaJuridica": { "get": { "tags": [ "Utilitários" ], "summary": "Semelhança dos dados com o bureau", "description": "Como validarPessoaFisica, para CNPJ: semelhança dos dados informados com o bureau, situação do CNPJ e se está inativo. Cada chamada consulta o bureau (serviço pago) e fica registrada. Só GET. Os parâmetros vão na query (ou no corpo como application/x-www-form-urlencoded); corpo JSON não é lido.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_validarPessoaJuridica", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "documento", "in": "query", "required": true, "schema": { "type": "string" }, "description": "CNPJ.", "example": "11222333000181" }, { "name": "razao_social", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "nome_fantasia", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "data_fundacao", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "AAAA-MM-DD." }, { "name": "cep", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CEP informado pelo cliente." }, { "name": "logradouro", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "numero", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "complemento", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "bairro", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "localidade", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cidade." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "UF." }, { "name": "telefone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Com DDD." }, { "name": "celular", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Com DDD." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "documento": "11222333000181", "dados_basicos": 0.9, "endereco": 1.0, "telefone": 1.0, "celular": 0.0, "email": 0.5, "cnpj_status": "ATIVA", "inativa": false, "pergunta1": { "Quais destes e-mails você reconhece?": [ { "0": "Nenhum" }, { "1": "financeiro@exemplo.com.br" } ] }, "pergunta2": { "Quais destes telefones você reconhece?": [ { "0": "Nenhum" }, { "1": "…" } ] }, "pergunta3": { "Quais destes endereços você reconhece?": [ { "0": "Nenhum" }, { "1": "…" } ] }, "token": "0123456789abcdef0123456789abcdef" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } }, "/v1/terceiro/txObservacao": { "get": { "tags": [ "Utilitários" ], "summary": "Consulta uma observação ou as de um registro", "description": "Por id_tx_observacao a resposta é um objeto plano (sem data[] e, no ZP, sem data_hora): {status, id_tx_observacao, tabela, id, observacao, ativo}.\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "get_txObservacao", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_tx_observacao", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Id da observação (tem prioridade)." }, { "name": "tabela", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tabela (usar junto com id quando não houver id_tx_observacao)." }, { "name": "id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Id do registro na tabela." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "data": [ { "id_tx_observacao": 15, "observacao": "Cliente pediu segunda via", "data_hora": "2026-11-10 09:30:00", "ativo": true } ] } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "post": { "tags": [ "Utilitários" ], "summary": "Cria uma observação", "description": "Grava e consulta observações (texto) ligadas a qualquer registro do sistema, identificado por tabela + id. GET por id_tx_observacao devolve uma; por tabela + id devolve a lista. DELETE desativa (ativo = N). A API não verifica se a tabela e o id existem e não restringe pelo escopo do acesso (só pelo app).\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "post_txObservacao", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tabela": { "type": "string", "description": "Nome da tabela do sistema a que a observação se refere (ex.: cob_cobranca)." }, "id": { "type": "integer", "description": "Id do registro nessa tabela." }, "observacao": { "type": "string", "description": "Texto" }, "ativo": { "type": "boolean", "description": "true/false" } }, "required": [ "tabela", "id", "observacao" ] }, "example": { "tabela": "cob_cobranca", "id": 5001, "observacao": "Cliente pediu segunda via" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok", "id_tx_observacao": 15 } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "put": { "tags": [ "Utilitários" ], "summary": "Altera uma observação (parcial)", "description": "Grava e consulta observações (texto) ligadas a qualquer registro do sistema, identificado por tabela + id. GET por id_tx_observacao devolve uma; por tabela + id devolve a lista. DELETE desativa (ativo = N). A API não verifica se a tabela e o id existem e não restringe pelo escopo do acesso (só pelo app).\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "put_txObservacao", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_tx_observacao", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Id da observação" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tabela": { "type": "string", "description": "Nome da tabela do sistema a que a observação se refere (ex.: cob_cobranca)." }, "id": { "type": "integer", "description": "Id do registro nessa tabela." }, "observacao": { "type": "string", "description": "Texto" }, "ativo": { "type": "boolean", "description": "true/false" } } }, "example": { "observacao": "Texto corrigido" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } }, "delete": { "tags": [ "Utilitários" ], "summary": "Desativa uma observação", "description": "Grava e consulta observações (texto) ligadas a qualquer registro do sistema, identificado por tabela + id. GET por id_tx_observacao devolve uma; por tabela + id devolve a lista. DELETE desativa (ativo = N). A API não verifica se a tabela e o id existem e não restringe pelo escopo do acesso (só pelo app).\n\n**Perfis**: App, Rede, Estabelecimento, Cliente, Pessoa.", "operationId": "delete_txObservacao", "x-perfis": [ "app", "rede", "estabelecimento", "cliente", "pessoa" ], "parameters": [ { "name": "id_tx_observacao", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Id da observação" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "status": "ok" } } } }, "400": { "$ref": "#/components/responses/Erro400" }, "401": { "$ref": "#/components/responses/Erro401" }, "403": { "$ref": "#/components/responses/Erro403" } } } } } }