Skip to main content

​
Endpoint

POST https://api.tiny.com.br/api2/conta.receber.incluir.php

​
Parâmetros

ParâmetroTipoOcorrênciaDescrição
tokenstringobrigatórioChave gerada para identificar sua empresa
contaobjectobrigatórioDados da conta conforme layout (1)
formatostringobrigatórioFormato do retorno (json)

​
Layout do parâmetro “conta”

Dados da conta:
CampoTipoTamanhoOcorrênciaDescrição
conta.datadate10opcionalData de emissão (formato dd/mm/yyyy)
conta.vencimentodate10obrigatórioVencimento da conta a receber
conta.valordecimal-obrigatórioValor da conta a receber (2)
conta.nro_documentostring9opcionalNúmero do documento
conta.historicostring300opcionalHistórico da conta a receber
conta.categoriastring100opcionalNome da categoria (3)
conta.competenciastring7opcionalFormato “mm/aaaa” (4)
conta.forma_pagamentostring30opcionalConforme Tabela de Formas de Pagamento
conta.portadorstring100opcionalNome do portador (5)
conta.ocorrenciastring1opcionalU, P, W, M, T, S, A (6)
conta.dia_vencimentoint2opcionalDia do vencimento (7)
conta.numero_parcelasint3opcionalMáximo 100 parcelas
conta.dia_semana_vencimentoint1opcional0-6 (domingo a sábado) (8)
Dados do cliente:
CampoTipoTamanhoOcorrênciaDescrição
conta.cliente.codigostring30opcionalCódigo do cliente (9)
conta.cliente.nomestring50obrigatórioNome do cliente (9)
conta.cliente.tipo_pessoastring1opcionalF (Física), J (Jurídica), E (Estrangeiro)
conta.cliente.cpf_cnpjstring18opcionalCPF ou CNPJ do cliente (9)
conta.cliente.iestring18opcionalInscrição estadual
conta.cliente.rgstring10opcionalRG do cliente
conta.cliente.enderecostring50opcionalEndereço do cliente
conta.cliente.numerostring10opcionalNúmero do endereço
conta.cliente.complementostring50opcionalComplemento do endereço
conta.cliente.bairrostring30opcionalBairro do cliente
conta.cliente.cepstring10opcionalCEP do cliente
conta.cliente.cidadestring30opcionalNome conforme Tabela de Cidades
conta.cliente.ufstring2opcionalUF do cliente
conta.cliente.paisstring50opcionalNome conforme Tabela de Países
conta.cliente.fonestring40opcionalTelefone do cliente
conta.cliente.emailstring50opcionalEmail do cliente
conta.cliente.atualizar_clientestring1opcional”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

CampoTipoTamanhoOcorrênciaDescrição
retornoobject-obrigatórioElemento raiz do retorno
retorno.status_processamentoint-obrigatórioConforme tabela “Status de Processamento”
retorno.statusstring-obrigatório”OK” ou “Erro”
retorno.codigo_erroint-obrigatórioConforme tabela “Códigos de erro”
retorno.erros[]list-condicionalLista dos erros encontrados [0..n]
retorno.erros[].errostring-condicionalDescrição do erro
retorno.registros[]list-condicionalLista de resultados
retorno.registros[].registro.sequenciaint-condicionalNúmero sequencial
retorno.registros[].registro.statusstring-condicional”OK” ou “Erro”
retorno.registros[].registro.codigo_erroint-condicionalCódigo do erro
retorno.registros[].registro.erros[]list-condicionalLista de erros [0..n]
retorno.registros[].registro.erros[].errostring-condicionalDescrição do erro
retorno.registros[].registro.idint-condicionalID da conta a receber na Olist

​
Exemplo de parâmetro

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

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

{
  "retorno": {
    "status_processamento": 1,
    "status": "Erro",
    "codigo_erro": 2,
    "erros": [
      {
        "erro": "token invalido"
      }
    ]
  }
}

​
Erro - Validação

{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "Erro",
          "codigo_erro": "31",
          "erros": [
            {
              "erro": "Preencha o valor"
            }
          ]
        }
      }
    ]
  }
}

​
Sucesso

{
  "retorno": {
    "status_processamento": 2,
    "status": "OK",
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "OK",
          "id": "49644545"
        }
      }
    ]
  }
}