5.1. Criar Escriturações¶

🔗 Endpoint¶

Método	URL
	`/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)¶

{
  "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¶

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¶

{
  "mensagem": "Duplicatas escrituradas com sucesso!",
  "identificador": "5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6",
  "identificadorProcessamento": null
}

✅ 202 Accepted¶

{
  "mensagem": "Escrituração recebida e será processada em breve.",
  "identificadorProcessamento": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
}

❌ 400 Bad Request¶

{
  "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.