> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.erp.olist.com/llms.txt > Use this file to discover all available pages before exploring further. # Incluir Conta a Receber > Serviço destinado a inclusão de contas a receber. ## Endpoint ``` POST https://api.tiny.com.br/api2/conta.receber.incluir.php ``` ## Parâmetros | Parâmetro | Tipo | Ocorrência | Descrição | | --------- | ------ | ----------- | ----------------------------------------- | | token | string | obrigatório | Chave gerada para identificar sua empresa | | conta | object | obrigatório | Dados da conta conforme layout (1) | | formato | string | obrigatório | Formato do retorno (json) | ### Layout do parâmetro "conta" **Dados da conta:** | Campo | Tipo | Tamanho | Ocorrência | Descrição | | ----------------------------- | ------- | ------- | ----------- | -------------------------------------- | | conta.data | date | 10 | opcional | Data de emissão (formato dd/mm/yyyy) | | conta.vencimento | date | 10 | obrigatório | Vencimento da conta a receber | | conta.valor | decimal | - | obrigatório | Valor da conta a receber (2) | | conta.nro\_documento | string | 9 | opcional | Número do documento | | conta.historico | string | 300 | opcional | Histórico da conta a receber | | conta.categoria | string | 100 | opcional | Nome da categoria (3) | | conta.competencia | string | 7 | opcional | Formato "mm/aaaa" (4) | | conta.forma\_pagamento | string | 30 | opcional | Conforme Tabela de Formas de Pagamento | | conta.portador | string | 100 | opcional | Nome do portador (5) | | conta.ocorrencia | string | 1 | opcional | U, P, W, M, T, S, A (6) | | conta.dia\_vencimento | int | 2 | opcional | Dia do vencimento (7) | | conta.numero\_parcelas | int | 3 | opcional | Máximo 100 parcelas | | conta.dia\_semana\_vencimento | int | 1 | opcional | 0-6 (domingo a sábado) (8) | **Dados do cliente:** | Campo | Tipo | Tamanho | Ocorrência | Descrição | | -------------------------------- | ------ | ------- | ----------- | ----------------------------------------- | | conta.cliente.codigo | string | 30 | opcional | Código do cliente (9) | | conta.cliente.nome | string | 50 | obrigatório | Nome do cliente (9) | | conta.cliente.tipo\_pessoa | string | 1 | opcional | F (Física), J (Jurídica), E (Estrangeiro) | | conta.cliente.cpf\_cnpj | string | 18 | opcional | CPF ou CNPJ do cliente (9) | | conta.cliente.ie | string | 18 | opcional | Inscrição estadual | | conta.cliente.rg | string | 10 | opcional | RG do cliente | | conta.cliente.endereco | string | 50 | opcional | Endereço do cliente | | conta.cliente.numero | string | 10 | opcional | Número do endereço | | conta.cliente.complemento | string | 50 | opcional | Complemento do endereço | | conta.cliente.bairro | string | 30 | opcional | Bairro do cliente | | conta.cliente.cep | string | 10 | opcional | CEP do cliente | | conta.cliente.cidade | string | 30 | opcional | Nome conforme Tabela de Cidades | | conta.cliente.uf | string | 2 | opcional | UF do cliente | | conta.cliente.pais | string | 50 | opcional | Nome conforme Tabela de Países | | conta.cliente.fone | string | 40 | opcional | Telefone do cliente | | conta.cliente.email | string | 50 | opcional | Email do cliente | | conta.cliente.atualizar\_cliente | string | 1 | opcional | "S" ou "N" (padrão "S") (10) | > (1) O parâmetro "conta" deve ser enviado em formato XML ou JSON > (2) Valores decimais usam ponto (.) como separador > (3) Categoria deixará vazia se não encontrada > (4) Competência requer módulo DRE instalado > (5) Portador receberá "Sem portador" se não encontrado > (6) Ocorrência: U (única), P (parcelada), W (semanal), M (mensal), T (trimestral), S (semestral), A (anual) > (7) Campo dia\_vencimento é obrigatório quando ocorrencia = "M" (mensal) > (8) Campo dia\_semana\_vencimento é obrigatório quando ocorrencia = "W" (semanal) > (9) Campos de cliente (código, nome, cpf\_cnpj) pesquisam cadastro existente; caso não exista, será criado automaticamente > (10) Se "S", atualiza dados do cliente existente; se "N", não atualiza ## Retorno | Campo | Tipo | Tamanho | Ocorrência | Descrição | | ------------------------------------------- | ------ | ------- | ----------- | ----------------------------------------- | | retorno | object | - | obrigatório | Elemento raiz do retorno | | retorno.status\_processamento | int | - | obrigatório | Conforme tabela "Status de Processamento" | | retorno.status | string | - | obrigatório | "OK" ou "Erro" | | retorno.codigo\_erro | int | - | obrigatório | Conforme tabela "Códigos de erro" | | retorno.erros\[] | list | - | condicional | Lista dos erros encontrados \[0..n] | | retorno.erros\[].erro | string | - | condicional | Descrição do erro | | retorno.registros\[] | list | - | condicional | Lista de resultados | | retorno.registros\[].registro.sequencia | int | - | condicional | Número sequencial | | retorno.registros\[].registro.status | string | - | condicional | "OK" ou "Erro" | | retorno.registros\[].registro.codigo\_erro | int | - | condicional | Código do erro | | retorno.registros\[].registro.erros\[] | list | - | condicional | Lista de erros \[0..n] | | retorno.registros\[].registro.erros\[].erro | string | - | condicional | Descrição do erro | | retorno.registros\[].registro.id | int | - | condicional | ID da conta a receber na Olist | ## Exemplo de parâmetro ```json theme={null} { "conta": { "cliente": { "codigo": "1235", "nome": "Contato Teste 2", "tipo_pessoa": "F", "cpf_cnpj": "22755777850", "endereco": "Rua Teste", "numero": "123", "complemento": "sala 2", "bairro": "Teste", "cep": "95700-000", "cidade": "Bento Gonçalves", "uf": "RS", "fone": "(54) 3055 3808", "email": "teste@teste.com.br", "atualizar_cliente": "N" }, "vencimento": "25/11/2015", "valor": 54.44, "historico": "teste teste xxx lalala", "categoria": "Faxina", "forma_pagamento": "boleto", "portador": "Bradesco", "ocorrencia": "P", "dia_vencimento": "4", "numero_parcelas": "4" } } ``` ## Exemplo de chamada ```bash theme={null} curl -X POST https://api.tiny.com.br/api2/conta.receber.incluir.php \ -d 'token=SEU_TOKEN&formato=json&conta={...}' ``` ## Exemplos de retorno ### Erro - Token inválido ```json theme={null} { "retorno": { "status_processamento": 1, "status": "Erro", "codigo_erro": 2, "erros": [ { "erro": "token invalido" } ] } } ``` ### Erro - Validação ```json theme={null} { "retorno": { "status_processamento": 2, "status": "Erro", "registros": [ { "registro": { "sequencia": "1", "status": "Erro", "codigo_erro": "31", "erros": [ { "erro": "Preencha o valor" } ] } } ] } } ``` ### Sucesso ```json theme={null} { "retorno": { "status_processamento": 2, "status": "OK", "registros": [ { "registro": { "sequencia": "1", "status": "OK", "id": "49644545" } } ] } } ```