--- title: 5.1. Criar Escriturações url: https://docs.vehub.com.br/API/VeFlow%20-%20Duplicata%20Escritural/5.%20Escritura%C3%A7%C3%B5es/v1/5.1.%20Criar%20Escritura%C3%A7%C3%B5es/ --- # 5.1. Criar Escriturações ## 🔗 Endpoint | Método | URL | |-------------------------------------------------|-----| | ![POST](https://img.shields.io/badge/POST-blue) | `/public/api/v1/duplicata-escritural/escrituracoes` | --- ## 🧾 Descrição Registra uma ou mais duplicatas escriturais no sistema. Cada duplicata deve conter os dados do sacador (emissor), sacado (devedor), dados do título, documentos fiscais vinculados e a lista de instrumentos de pagamento configurados. --- ## 📤 Requisição ### 📋 Payload (JSON) ```json { "duplicatas": [ { "sacador": { "numeroDocumento": "12345678000199", "nomeRazaoSocial": "Empresa Cedente LTDA" }, "sacado": { "numeroDocumento": "98765432000155", "nomeRazaoSocial": "Empresa Sacada S.A.", "inscricaoEstadual": "123456789", "email": "financeiro@sacada.com.br", "telefone": "11999999999", "cpfResponsavelManifestacao": "12345678901", "endereco": { "logradouro": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista", "cep": "01310100", "municipio": "São Paulo", "uf": "SP" } }, "dadosTitulo": { "tipoDuplicata": 1, "liberadoNegociacao": true, "numeroFatura": "FAT-2025-001", "valorFatura": 10000.00, "valorDesconto": 0.00, "numeroParcela": "1/1", "dataEmissao": "2025-09-01", "dataVencimento": "2025-10-01", "valorDuplicata": 10000.00, "codigoPracaPagamento": "01310100" }, "documentosFiscais": [ { "tipoDocumentoFiscal": 1, "chaveDocumentoFiscal": "35250912345678000199550010000012341234567890", "numeroDocumentoFiscal": "000001234", "serieDocumentoFiscal": "001" } ], "instrumentoPagamento": [ { "tipoInstrumentoPagamento": 2, "pix": { "tipoChave": 2, "chave": "12345678000199" } } ], "avalistas": [ { "tipoAval": 1, "cpfOuCnpjAvalista": "12345678901", "nomeOuRazaoSocialAvalista": "João da Silva", "tipoEstadoCivilAvalista": 2, "cpfConjugeAvalista": "98765432100", "nomeConjugeAvalista": "Maria da Silva", "logradouroAvalista": "Rua das Flores", "numeroLogradouroAvalista": "42", "complementoLogradouroAvalista": "Apto 101", "bairroAvalista": "Centro", "cepAvalista": "01310100", "cidadeAvalista": "São Paulo", "ufAvalista": "SP", "tipoAssinaturaAvalista": 1, "assinaturaAvalista": "João da Silva", "emailAvalista": "joao@exemplo.com.br" } ] } ] } ``` ### 🧾 Detalhamento dos Campos | Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | duplicatas | array | Sim | Lista de duplicatas a escriturar | #### 🔹 sacador | Campo | Tipo | Obrigatório | Descrição | |-----------------|---------|-------------|-----------| | numeroDocumento | string | Sim | CPF ou CNPJ do sacador (somente números) | | nomeRazaoSocial | string | Sim | Nome ou razão social do sacador | #### 🔹 sacado | Campo | Tipo | Obrigatório | Descrição | |----------------------------|---------|-------------|-----------| | numeroDocumento | string | Sim | CPF ou CNPJ do sacado (somente números) | | nomeRazaoSocial | string | Sim | Nome ou razão social do sacado | | inscricaoEstadual | string | Não | Inscrição estadual do sacado | | email | string | Sim | E-mail do sacado | | telefone | string | Sim | Telefone do sacado (somente números) | | cpfResponsavelManifestacao | string | Sim | CPF do responsável pela manifestação (somente números) | | endereco | object | Sim | Endereço do sacado | #### 🔹 sacado.endereco | Campo | Tipo | Obrigatório | Descrição | |------------|--------|-------------|-----------| | logradouro | string | Sim | Logradouro (rua, avenida, etc.) | | numero | string | Sim | Número do endereço | | bairro | string | Sim | Bairro | | cep | string | Sim | CEP (somente números) | | municipio | string | Sim | Município | | uf | string | Sim | UF (sigla do estado, ex: SP) | #### 🔹 dadosTitulo | Campo | Tipo | Obrigatório | Descrição | |---------------------|---------|-------------|-----------| | tipoDuplicata | integer | Sim | Tipo da duplicata (ver TipoDuplicata) | | liberadoNegociacao | boolean | Sim | Indica se a duplicata está liberada para negociação | | numeroFatura | string | Sim | Número da fatura de origem | | valorFatura | number | Sim | Valor total da fatura | | valorDesconto | number | Sim | Valor de desconto aplicado | | numeroParcela | string | Sim | Número da parcela (ex: `1/3`) | | dataEmissao | string | Sim | Data de emissão da duplicata (YYYY-MM-DD) | | dataVencimento | string | Sim | Data de vencimento da duplicata (YYYY-MM-DD) | | valorDuplicata | number | Sim | Valor da duplicata | | codigoPracaPagamento| string | Sim | CEP ou código da praça de pagamento | #### 🔹 documentosFiscais | Campo | Tipo | Obrigatório | Descrição | |------------------------|---------|-------------|-----------| | tipoDocumentoFiscal | integer | Sim | Tipo do documento fiscal (ver TipoDocumentoFiscal) | | chaveDocumentoFiscal | string | Sim | Chave eletrônica do documento fiscal | | numeroDocumentoFiscal | string | Sim | Número do documento fiscal | | serieDocumentoFiscal | string | Sim | Série do documento fiscal | #### 🔹 instrumentoPagamento[] | Campo | Tipo | Obrigatório | Descrição | |--------------------------|---------|-------------|-----------| | tipoInstrumentoPagamento | integer | Sim | Tipo do instrumento (ver TipoInstrumentoPagamento) | | boleto | object | Condicional | Dados do boleto (obrigatório quando tipo = 1) | | pix | object | Condicional | Dados do PIX (obrigatório quando tipo = 2) | | ted | object | Condicional | Dados do TED (obrigatório quando tipo = 3) | #### 🔹 instrumentoPagamento[].boleto | Campo | Tipo | Obrigatório | Descrição | |---------------------------|---------|-------------|-----------| | numeroLinhaDigitavel | string | Sim | Linha digitável do boleto | | tipoBoleto | integer | Sim | Tipo do boleto (ver TipoBoleto) | | numeroIdentificacaoBoleto | string | Sim | Número de identificação do boleto | #### 🔹 instrumentoPagamento[].pix | Campo | Tipo | Obrigatório | Descrição | |----------|---------|-------------|-----------| | tipoChave | integer | Sim | Tipo da chave PIX (ver TipoChavePix) | | chave | string | Sim | Valor da chave PIX | #### 🔹 instrumentoPagamento[].ted | Campo | Tipo | Obrigatório | Descrição | |---------------------|---------|-------------|-----------| | codigoBanco | string | Sim | Código COMPE do banco | | agencia | string | Sim | Agência bancária | | digitoAgencia | string | Sim | Dígito verificador da agência | | numeroConta | string | Sim | Número da conta | | digitoConta | string | Sim | Dígito verificador da conta | | cpfCnpjTitularConta | string | Sim | CPF ou CNPJ do titular (somente números) | | tipoConta | integer | Sim | Tipo da conta (ver TipoConta) | #### 🔹 avalistas[] | Campo | Tipo | Obrigatório | Descrição | |--------------------------------|---------|--------------|-----------| | tipoAval | integer | Sim | Tipo do aval (ver TipoAval) | | cpfOuCnpjAvalista | string | Sim | CPF ou CNPJ do avalista (somente números) | | nomeOuRazaoSocialAvalista | string | Sim | Nome ou razão social do avalista | | tipoEstadoCivilAvalista | integer | Condicional | Estado civil do avalista (ver EstadoCivil) — obrigatório quando o avalista for pessoa física (CPF) | | cpfConjugeAvalista | string | Não | CPF do cônjuge (somente números) | | nomeConjugeAvalista | string | Não | Nome do cônjuge | | logradouroAvalista | string | Sim | Logradouro do avalista | | numeroLogradouroAvalista | string | Sim | Número do logradouro | | complementoLogradouroAvalista | string | Não | Complemento do logradouro | | bairroAvalista | string | Sim | Bairro | | cepAvalista | string | Sim | CEP (somente números) | | cidadeAvalista | string | Sim | Cidade | | ufAvalista | string | Sim | UF (2 caracteres, ex: SP) | | tipoAssinaturaAvalista | integer | Sim | Tipo de assinatura (ver TipoAssinatura) | | assinaturaAvalista | string | Sim | Assinatura do avalista | | emailAvalista | string | Sim | E-mail do avalista | --- ## 🔢 Enumeradores ### TipoDuplicata | Código | Significado | |--------|-------------| | 1 | Mercantil | | 2 | Servicos | | 3 | Rural | | 4 | Outros | ### TipoDocumentoFiscal | Código | Significado | Descrição | |--------|-------------|-----------| | 1 | SAT_CFE | Cupom Fiscal Eletrônico | | 2 | NFC_E | Nota Fiscal de Consumidor eletrônica | | 3 | NF_E | Nota Fiscal eletrônica | | 4 | NFS_E | Nota Fiscal de Serviços eletrônica | | 5 | CT_E | Conhecimento de Transporte eletrônico | | 6 | MDF_E | Manifesto Eletrônico de Documentos Fiscais | | 7 | RPA | Recibo de Pagamento Autônomo | ### TipoInstrumentoPagamento | Código | Significado | |--------|-------------| | 1 | Boleto | | 2 | PIX | | 3 | TED | ### TipoBoleto | Valor | Código | Significado | |-------|--------|-------------| | 1 | BS | Boleto simples | | 2 | BD | Boleto dinâmico | ### TipoChavePix | Código | Significado | |--------|-------------| | 1 | CPF | | 2 | CNPJ | | 3 | E-mail | | 4 | Telefone | | 5 | Chave Aleatória | ### TipoConta | Código | Significado | |--------|-------------| | 1 | Corrente | | 2 | Poupança | | 3 | Escrow | ### TipoAval | Código | Significado | |--------|-------------| | 1 | Aval | | 2 | Aval com anuência do cônjuge | ### EstadoCivil | Código | Significado | |--------|-------------| | 1 | Solteiro | | 2 | Casado ou em União Estável, com comunhão universal | | 3 | Casado ou em União Estável com comunhão parcial | | 4 | Casado ou em União Estável com separação total | | 5 | Casado ou em União Estável com separação obrigatória | | 6 | Viúvo | | 7 | Divorciado | | 8 | Participação final nos aquestos | ### TipoAssinatura | Valor | Código | Significado | |-------|--------|-------------| | 1 | ELEC | Eletrônica | | 2 | DIGI | Digital | | 3 | OUTR | Outros | --- ## 🧪 Exemplo de cURL ```bash curl -X POST https://api.vehub.com.br/public/api/v1/duplicata-escritural/escrituracoes \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Content-Type: application/json" \ -d '{ "duplicatas": [ { "sacador": { "numeroDocumento": "12345678000199", "nomeRazaoSocial": "Empresa Cedente LTDA" }, "sacado": { "numeroDocumento": "98765432000155", "nomeRazaoSocial": "Empresa Sacada S.A.", "email": "financeiro@sacada.com.br", "telefone": "11999999999", "cpfResponsavelManifestacao": "12345678901", "endereco": { "logradouro": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista", "cep": "01310100", "municipio": "São Paulo", "uf": "SP" } }, "dadosTitulo": { "tipoDuplicata": 1, "liberadoNegociacao": true, "numeroFatura": "FAT-2025-001", "valorFatura": 10000.00, "valorDesconto": 0.00, "numeroParcela": "1/1", "dataEmissao": "2025-09-01", "dataVencimento": "2025-10-01", "valorDuplicata": 10000.00, "codigoPracaPagamento": "01310100" }, "documentosFiscais": [ { "tipoDocumentoFiscal": 1, "chaveDocumentoFiscal": "35250912345678000199550010000012341234567890", "numeroDocumentoFiscal": "000001234", "serieDocumentoFiscal": "001" } ], "instrumentoPagamento": [ { "tipoInstrumentoPagamento": 2, "pix": { "tipoChave": 2, "chave": "12345678000199" } } ] } ] }' ``` --- ## 📥 Responses ### ✅ 200 OK ```json { "mensagem": "Duplicatas escrituradas com sucesso!", "identificador": "5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6", "identificadorProcessamento": null } ``` --- ### ✅ 202 Accepted ```json { "mensagem": "Escrituração recebida e será processada em breve.", "identificadorProcessamento": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890" } ``` --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "Campo 'sacado.email' é obrigatório.", "Campo 'dadosTitulo.dataVencimento' deve ser uma data futura." ] } ``` --- ## 🕒 Observações - É possível enviar múltiplas duplicatas em um único request através do array `duplicatas`. - O campo `instrumentoPagamento` é uma lista — cada duplicata pode ter um ou mais instrumentos de pagamento. - O bloco `instrumentoPagamento[].boleto` é obrigatório quando `tipoInstrumentoPagamento = 1`. - O bloco `instrumentoPagamento[].pix` é obrigatório quando `tipoInstrumentoPagamento = 2`. - O bloco `instrumentoPagamento[].ted` é obrigatório quando `tipoInstrumentoPagamento = 3`. - O array `avalistas` é opcional. Quando informado, todos os campos obrigatórios do avalista devem ser preenchidos. - O campo `tipoEstadoCivilAvalista` é obrigatório apenas quando o avalista for pessoa física (CPF). - Quando o retorno for `202 Accepted`, o processamento ocorrerá de forma assíncrona.