API Consultiva v2 — Manual Técnico

Olá! Para entender melhor o funcionamento da API Consultiva do ssOtica, acesse também o material "Entendendo a API Consultiva", disponível na Central de Ajuda.

Para o passo a passo de acesso, consulte também o material "Passo-a-passo para acessar a API do ssOtica".

Estão disponíveis os seguintes processos de consulta via API:

1. Vendas ativas do ssOtica
2. Ordens de Serviço
3. Lançamentos Financeiros
4. Produtos, estoque, reservados em O.S., preço, grupo, grife e fornecedores
5. Contas a Pagar
6. Contas a Receber
7. Clientes
8. Funcionários
9. Formas de Pagamento
10. Saldos das Contas

Parâmetros gerais

Para os endpoints por período, utilize os parâmetros abaixo:

• empresa: chave de identificação da empresa (Código da Licença), enviada por e-mail após a contratação. Em alguns endpoints é aceito também o parâmetro cnpj (CNPJ sem pontuação).
• inicio_periodo: data de início no formato AAAA-MM-DD.
• fim_periodo: data final do período no formato AAAA-MM-DD.

Os parâmetros acima valem para os endpoints por período. As consultas de Produtos/Estoque, Contas a Pagar e Contas a Receber usam parâmetros próprios, detalhados em cada seção.

Caso encontre algum problema na consulta, verifique se os parâmetros na URL (endpoint) estão configurados corretamente.

Segurança

A autenticação é feita via Bearer Token no cabeçalho (header) da requisição GET:

Authorization: Bearer XXXyyyXXXyXXXXXXXXXXyXXXyXXXyXXX

Paginação

Os endpoints suportam paginação por dois parâmetros de query string:

• page: número da página desejada (padrão 1).
• perPage: quantidade de itens por página (máximo 100).

Quando a resposta é paginada, ela vem no seguinte formato (envelope):

{
  "currentPage": 1,
  "totalPages": 5,
  "totalItems": 437,
  "perPage": 100,
  "data": [ ... ]
}

• currentPage: página atual retornada.
• totalPages: total de páginas disponíveis.
• totalItems: total de registros encontrados (sem paginação).
• perPage: itens por página aplicado.
• data: registros da página atual.

Exemplo de cálculo de páginas

A quantidade total de páginas é calculada com base no total de itens da busca. Por exemplo, com 234 itens e perPage = 100:

• Página 1: itens 1 a 100;
• Página 2: itens 101 a 200;
• Página 3: itens 201 a 234.

Basta ajustar o número da página (page) para percorrer os resultados.

Comportamento por endpoint

Padronização de mensagens de erro

Em caso de erro, a API responde com status HTTP 400 no formato:

{
  "error": "PERIODO_EXCEDE_LIMITE",
  "error_info": "O intervalo entre \"inicio_periodo\" e \"fim_periodo\" excede o limite máximo de 180 dias."
}

• error: código estável do erro (use este campo para tratar o erro na integração).
• error_info: mensagem descritiva, para leitura humana.

Catálogo de códigos de erro

1. Vendas

Retorna as vendas ativas no período (não inclui vendas canceladas ou excluídas).

Endpoint — GET

https://app.ssotica.com.br/api/v1/integracoes/vendas/periodo?cnpj=07585769000168&inicio_periodo=2021-02-01&fim_periodo=2021-02-28

Informações retornadas: dados da venda (id, data, hora, status, numero, valores), itens da venda (itens), formas de pagamento (formas_pagamento), cliente (cliente), funcionário (funcionario) e origens do cliente (origensCliente).

Exemplo de retorno

[
  {
    "id": 22844285,
    "data": "2023-01-12",
    "hora": "10:02:25",
    "status": "ATIVA",
    "numero": 5728,
    "valor_bruto": 595,
    "acrescimo": 0,
    "desconto": 17.05,
    "credito_troca": 577.95,
    "valor_liquido": 0,
    "itens": [
      {
        "id": 43278661,
        "produto": {
          "id": 458095,
          "referencia": "V/S CR-39 ESF. 2,25 A 4,00 C/ CIL ATÉ 5,00",
          "descricao": "Lente Oftalmica",
          "grupo": "Lentes Oftálmicas",
          "grupo_id": 19206,
          "grife": "** Não Especificado **",
          "grife_id": 277112,
          "unidade": "PR",
          "codigo_gtin": null
        },
        "quantidade": 1,
        "custo": 0,
        "valor_unitario_bruto": 595,
        "desconto": 17.05,
        "acrescimo": 0,
        "valor_unitario_liquido": 577.95,
        "valor_total_liquido": 577.95
      }
    ],
    "formas_pagamento": [],
    "cliente": {
      "id": 16813359,
      "nome": "João da Silva",
      "apelido": "Jô",
      "nascimento": "1956-05-01",
      "cpf_cnpj": "000.000.000-00",
      "rg_ie": "00000000",
      "nome_pai": "José da Silva",
      "nome_mae": "Francisca da Silva",
      "profissao": "Agricultor",
      "observacao": "",
      "ativo": true,
      "contribuinte_icms": false,
      "suframa": null,
      "ie": null,
      "im": null,
      "tipo": "PF",
      "cadastrado_em": "2022-05-31 11:44:56",
      "sexo": "M",
      "renda_familiar": "0.00",
      "codigo": null,
      "convenio": "",
      "escolaridade": "MEDIO_INCOMPLETO",
      "referencia": null,
      "endereco": {
        "logradouro": "Av das Flores",
        "numero": "S/N",
        "complemento": "",
        "bairro": "",
        "cep": "00.000-000",
        "cidade": "Cruz",
        "uf": "CE",
        "pais": "Brasil"
      },
      "telefones": [ { "numero": "(00) 9.00000-0000", "identificacao": "" } ],
      "emails": [ { "email": "exemplo@email.com", "identificacao": "" } ],
      "origem": ""
    },
    "funcionario": {
      "id": 105287,
      "nome": "Maria Aparecida",
      "cpf": "000.000.000-00",
      "rg": "0000000000",
      "telefone_fixo": "",
      "telefone_movel": "(88) 9.0000-0000",
      "endereco": {
        "logradouro": "Flores",
        "bairro": "Zona Rural",
        "cep": "00.000-000",
        "cidade": "Cruz",
        "uf": "CE"
      },
      "funcao": "Vendedor",
      "observacao": ""
    },
    "origensCliente": []
  }
]

2. Ordens de Serviço

Endpoint — GET

https://app.ssotica.com.br/api/v1/integracoes/ordens-servico/periodo?cnpj=XXX&inicio_periodo=2023-01-12&fim_periodo=2023-01-12

Dados retornados: dados da ordem de serviço, receita (receita), funcionário (funcionario), produtos (itens), adiantamentos (formas_pagamento), cliente (cliente) e origens do cliente (origensCliente).

Exemplo de retorno

[
  {
    "id": 999,
    "numero": 9999,
    "codigo_os_externo": null,
    "tipo_os": "Ótica",
    "etapa_atual": "Serviço Pronto - Cliente Avisado",
    "status": "ABERTO",
    "data": "2023-01-12",
    "previsao_entrega": "2023-01-19",
    "data_entrega": "",
    "valor_bruto": "1429.90",
    "acrescimo": 0,
    "desconto": "29.90",
    "valor_liquido": 1400,
    "tipo_armacao": "Metal",
    "material_lente": "Resina",
    "aro": "54",
    "ponte": "17",
    "maior_diagonal": "54",
    "altura_vertical": "42",
    "descricao_material_lente": null,
    "descricao_lente": "xxxxxxxxxxxxxxx",
    "descricao_coloracao": "",
    "tipo_lente": "SURFAÇADA",
    "distancia_pupilar": "0.00",
    "altura_centro_otico": {
      "altura_od_longe": "",
      "altura_od_perto": "",
      "altura_oe_longe": "",
      "altura_oe_perto": ""
    },
    "possui_receita": 1,
    "possui_armacao": 0,
    "segue_armacao": 1,
    "local_montagem": "LABORATORIO",
    "gaveta_caixa": "",
    "receita": {
      "id": 9999999,
      "esferico_oe_longe": -1.5,
      "esferico_oe_perto": 2,
      "cilindrico_oe_longe": -3,
      "cilindrico_oe_perto": -3,
      "prisma_oe_longe": null,
      "prisma_oe_perto": null,
      "base_oe_longe": null,
      "base_oe_perto": null,
      "eixo_oe_longe": 90,
      "eixo_oe_perto": 90,
      "altura_oe_longe": 25,
      "altura_oe_perto": null,
      "dnp_oe_longe": 27.5,
      "dnp_oe_perto": null,
      "distancia_pupila_oe": null,
      "percentual_visao_oe": null,
      "desconto_oe": null,
      "ceratometria_oe_longe": null,
      "esferico_od_longe": -2.25,
      "esferico_od_perto": 1.25,
      "cilindrico_od_longe": -1,
      "cilindrico_od_perto": -1,
      "prisma_od_longe": null,
      "prisma_od_perto": null,
      "base_od_longe": null,
      "base_od_perto": null,
      "eixo_od_longe": 15,
      "eixo_od_perto": 15,
      "altura_od_longe": 25,
      "altura_od_perto": null,
      "dnp_od_longe": 26.5,
      "dnp_od_perto": null,
      "distancia_pupila_od": null,
      "percentual_visao_od": null,
      "desconto_od": null,
      "ceratometria_od_longe": null,
      "adicao": 3.5,
      "validade": "2024-01-12 00:00:00",
      "observacao": "Multi em dobro 2º aro clip on",
      "curva_base": null,
      "olho_dominante": null,
      "ceratometria_od_horizontal": null,
      "ceratometria_od_horizontal_eixo": null,
      "ceratometria_od_vertical": null,
      "ceratometria_od_vertical_eixo": null,
      "ceratometria_oe_horizontal": null,
      "ceratometria_oe_horizontal_eixo": null,
      "ceratometria_oe_vertical": null,
      "ceratometria_oe_vertical_eixo": null,
      "indicacao": null,
      "dnp_oe": null,
      "dnp_od": null,
      "altura_oe": null,
      "altura_od": null,
      "diametro_lente_oe": null,
      "diametro_lente_od": null,
      "angulo_pantoscopico": null,
      "medido_pupilometro": null,
      "layout_novo": 0,
      "medicao_id": null,
      "optometrista": "Nome Optometrista"
    },
    "observacao": "",
    "ocorrencias": null,
    "responsavel_tecnico": "",
    "funcionario": {
      "id": 9999,
      "nome": "Nome do Funcionário",
      "cpf": "",
      "rg": "",
      "telefone_fixo": "",
      "telefone_movel": "",
      "endereco": { "logradouro": "", "bairro": "", "cep": "", "cidade": "", "uf": "" },
      "funcao": "Vendedor",
      "observacao": ""
    },
    "itens": [
      {
        "id": 9999,
        "produto": {
          "id": 9999, "referencia": "XXXXX", "descricao": "1.56 Hiper Clean Sha",
          "grupo": "Multifocal Free Form", "grife": "XXXXXXX", "unidade": "UN", "codigo_gtin": null
        },
        "quantidade": "1.0000",
        "desconto": 20.91, "acrescimo": 0,
        "valor_unitario_liquido": "979.0900", "valor_total_liquido": 979.09, "custo": 150
      },
      {
        "id": 9999,
        "produto": {
          "id": 9999, "referencia": "52335 C2", "descricao": "Armação Rx (Grau) Feminino",
          "grupo": "Rx", "grife": "XXXXXXX", "unidade": "UN", "codigo_gtin": null
        },
        "quantidade": "1.0000",
        "desconto": 2.93, "acrescimo": 0,
        "valor_unitario_liquido": "136.9700", "valor_total_liquido": 136.97, "custo": 79.9
      },
      {
        "id": 9999,
        "produto": {
          "id": 9999, "referencia": "YS3867 C1", "descricao": "Armação Rx Feminino Clip On",
          "grupo": "Clip On", "grife": "XXXXXXX", "unidade": "UN", "codigo_gtin": null
        },
        "quantidade": "1.0000",
        "desconto": 6.06, "acrescimo": 0,
        "valor_unitario_liquido": "283.9400", "valor_total_liquido": 283.94, "custo": 129
      }
    ],
    "formas_pagamento": [
      { "id": 9999, "data": "2023-01-12", "valor": "700.00", "qtd_parcelas": 1, "forma_pagamento": "Pix", "codigo_autorizacao": null }
    ],
    "cliente": {
      "id": 99999,
      "nome": "NOME DO CLIENTE",
      "apelido": "",
      "nascimento": "1954-10-23",
      "cpf_cnpj": "999.999.999-99",
      "rg_ie": "",
      "nome_pai": "",
      "nome_mae": "",
      "profissao": null,
      "observacao": "",
      "ativo": true,
      "contribuinte_icms": false,
      "suframa": null,
      "ie": null,
      "im": null,
      "tipo": "PF",
      "cadastrado_em": "2023-01-12 14:42:09",
      "sexo": "F",
      "renda_familiar": "0.00",
      "codigo": null,
      "convenio": "",
      "escolaridade": null,
      "referencia": null,
      "endereco": { "logradouro": "XXXXX", "numero": "600", "complemento": "Apto 4101", "bairro": "", "cep": "", "cidade": "XXXXX", "uf": "SP", "pais": "Brasil" },
      "telefones": [ { "numero": "(99) 9.9999-9999", "identificacao": "" } ],
      "emails": [ { "email": "xxxx@email.com", "identificacao": "" } ],
      "origem": "Instagram"
    },
    "origensCliente": [ "Instagram" ]
  }
]

3. Lançamentos Financeiros

Endpoint — GET

https://app.ssotica.com.br/api/v1/integracoes/financeiro/extrato/periodo?cnpj=XXX&inicio_periodo=2023-01-12&fim_periodo=2023-01-12

Campos retornados

• data_operacao: data de lançamento do registro.
• data_credito: data de efetivação do lançamento.
• codigo_autorizacao_adquirente: código de autorização para transações de cartão de crédito.
• valor: valor do lançamento.
• tipo: indica se o lançamento é CREDITO ou DEBITO (positivo ou negativo). Não significa que seja RECEITA ou DESPESA — essa informação está na categoria. Um lançamento de categoria RECEITA pode ser do tipo DÉBITO (saída), o que geralmente ocorre em estornos, em que o lançamento negativo cancela o positivo.
• descricao: descrição detalhada do lançamento.
• numero_documento / tipo_documento: número e tipo do documento informado.
• forma_recebimento: dados da forma de recebimento vinculada (id, nome, tipo).
• conta: dados da conta vinculada (id, descricao).
• categoria: categoria do lançamento; permite saber se é RECEITA ou DESPESA. Se for subcategoria, traz também a categoria pai (conta_pai). Campo tipo: CREDITO (receita) ou DEBITO (despesa).
• cliente: dados completos do cliente vinculado (quando existir).
• venda: dados da venda vinculada (quando for recebimento de venda).
• ordem_servico: dados da O.S. vinculada (quando for adiantamento de O.S.).
• fornecedor: dados do fornecedor vinculado (quando for "Contas a Pagar").

Exemplo de retorno

{
  "data_operacao": "2020-02-12",
  "data_credito": "2020-02-12",
  "codigo_autorizacao_adquirente": "038043",
  "valor": 116.5,
  "tipo": "CREDITO",
  "descricao": "Recebimento de venda no. 1570. Parcela 3/4",
  "numero_documento": "venda 1570",
  "forma_recebimento": {
    "id": 51976,
    "nome": "Cartao de Credito Parcelado 2 Ate 6X",
    "tipo": "Cartão de Crédito/débito"
  },
  "conta": { "id": 26407, "descricao": "Banco" },
  "categoria": {
    "id": 388677,
    "descricao": "Vendas",
    "tipo": "CREDITO",
    "conta_pai": { "id": 388676, "descricao": "Receitas de Vendas", "tipo": "CREDITO" }
  },
  "cliente": {
    "id": 7428731,
    "nome": "Nome do Cliente",
    "nascimento": "",
    "cpf_cnpj": "000.000.000-00",
    "ativo": true,
    "contribuinte_icms": false,
    "tipo": "PF",
    "cadastrado_em": "2020-02-12 11:05:51",
    "convenio": "",
    "endereco": { "cep": "", "pais": "Brasil" },
    "telefones": [ { "numero": "(61) 9.0000-0000", "identificacao": null } ],
    "emails": []
  },
  "venda": { "id": 7714210, "numero": 1570, "data": "2020-02-12", "valor": 466 }
}

Quando o lançamento for um adiantamento de O.S., em vez de venda vem o objeto ordem_servico; quando for um Contas a Pagar com fornecedor vinculado, vem o objeto fornecedor.

4. Produtos, Estoque, Preço, Grupo, Grife e Fornecedores

Endpoint — GET

https://app.ssotica.com.br/api/v1/produto/estoque/busca?empresa=XXXX-XXXX&page=1&perPage=100

Parâmetros

• empresa: Código da Licença.
• referencia: referência do produto para busca.
• id: ID do produto para busca.
• page: página a ser retornada (obrigatório informar; padrão 1).
• perPage: itens por página (máximo 100).

Campos retornados (cada produto em data)

• id, referencia, descricao, unidade.
• grife / grife_id, grupo / grupo_id, subgrupo / subgrupo_id.
• cor, tamanho, formato.
• fornecedores: lista com id, documento, razao_social, nome_fantasia.
• estoque_atual, reservado_os, preco_venda, preco_custo.
• ativo, codigo_ean, imagens.
• criado_em, criado_por, atualizado_em, atualizado_por.

Exemplo de retorno

{
  "currentPage": 1,
  "totalPages": 1,
  "totalItems": 4,
  "perPage": 100,
  "data": [
    {
      "id": 123456,
      "referencia": "04",
      "descricao": "Armação de Cristal",
      "unidade": "UN",
      "grife": "Acrílica",
      "grife_id": 2782289,
      "grupo": "Acessórios",
      "grupo_id": 19206,
      "subgrupo": "Cristais",
      "subgrupo_id": 2,
      "cor": "Preta",
      "tamanho": "M",
      "formato": "Retangular",
      "fornecedores": [
        { "id": 230563, "documento": "00.000.000/0001-00", "razao_social": "Fornecedor LTDA", "nome_fantasia": "Fornecedor" }
      ],
      "estoque_atual": 10,
      "reservado_os": 2,
      "preco_venda": 199.90,
      "preco_custo": 89.90,
      "ativo": true,
      "codigo_ean": "7890000000000",
      "imagens": [ "https://.../imagem.jpg" ],
      "criado_em": "2024-05-10 09:00:00",
      "criado_por": "Usuário",
      "atualizado_em": "2024-06-01 14:30:00",
      "atualizado_por": "Usuário"
    }
  ]
}

5. Contas a Pagar

Endpoint — GET

https://app.ssotica.com.br/api/v1/integracoes/financeiro/contas-a-pagar/periodo?empresa=XXXX-XXXX&inicio_periodo=2025-08-01&fim_periodo=2025-08-31

Parâmetros

• empresa: Código da Licença.
• inicio_periodo / fim_periodo: período no formato AAAA-MM-DD.
• tipo_periodo: vencimento (padrão), cancelamento, pagamento, lançamento ou emissao.
• id: ID da conta a pagar. Ao filtrar por ID, os demais parâmetros são ignorados.
• page / perPage: paginação (máximo 100 por página).
• documento: número do documento.
• emissao: data de emissão da conta.

Campos retornados (cada parcela em data)

• id, numero_parcela, vencimento, situacao (ex.: "Pago", "Em Aberto", "Cancelado").
• arquivos: anexo e comprovante (links).
• baixado_por / baixado_em, cancelado_por / cancelado_em / motivo_cancelamento.
• valor_original, juros, desconto, valor_pago, observacao.
• titulo: id, documento, lancamento, criado_por, data_emissao, valor, mes_competencia, qtd_parcelas, plano_conta, tipo_documento, descricao, quitado ("Sim"/"Não").
• fornecedor: id, nome_fantasia, razao_social, documento, laboratorio, email, inscricao_estadual, inscricao_municipal, suframa, contribuinte_icms.
• ocorrencias_caixa: registros relacionados a ocorrências de caixa.
• ocorrencias: histórico do título — inclusão, última edição e exclusões (detalhado abaixo).

Exemplo de retorno

{
  "currentPage": 1,
  "totalPages": 1,
  "totalItems": 1,
  "perPage": 10,
  "data": [
    {
      "id": 350,
      "numero_parcela": 1,
      "vencimento": "2025-08-21",
      "situacao": "Pago",
      "arquivos": { "anexo": "https://.../anexo.pdf", "comprovante": "https://.../comprovante.pdf" },
      "baixado_por": "Dev",
      "baixado_em": "2025-08-21 15:43:40",
      "cancelado_por": null,
      "cancelado_em": null,
      "motivo_cancelamento": null,
      "valor_original": 100,
      "juros": 0,
      "desconto": 0,
      "valor_pago": 100,
      "observacao": "",
      "titulo": {
        "id": 63,
        "documento": "Teste 123",
        "lancamento": "2025-08-21",
        "criado_por": "Dev",
        "data_emissao": "2025-08-21",
        "valor": 100,
        "mes_competencia": "08/2025",
        "qtd_parcelas": 1,
        "plano_conta": "Despesas Administrativas e Comerciais",
        "tipo_documento": "Carné",
        "descricao": "Pagamento fornecedor",
        "quitado": "Sim"
      },
      "fornecedor": {
        "id": 230563,
        "nome_fantasia": "Geral",
        "razao_social": "*** Não Especificado ***",
        "documento": "",
        "laboratorio": "Não",
        "email": "",
        "inscricao_estadual": "",
        "inscricao_municipal": "",
        "suframa": "",
        "contribuinte_icms": "Não"
      },
      "ocorrencias_caixa": [],
      "ocorrencias": [
        { "tipo": "INCLUSAO", "usuario": "Ana Souza",  "data": "2025-08-19", "hora": "10:02:25" },
        { "tipo": "EDICAO",   "usuario": "Carlos Lima", "data": "2025-08-20", "hora": "14:31:08" },
        { "tipo": "EXCLUSAO", "usuario": "Ana Souza",  "data": "2025-08-22", "hora": "09:15:40", "motivo": "Lançamento duplicado" }
      ]
    }
  ]
}

6. Contas a Receber

Endpoint — GET

https://app.ssotica.com.br/api/v1/integracoes/financeiro/contas-a-receber/periodo?empresa=XXXX-XXXX&inicio_periodo=2025-08-01&fim_periodo=2025-08-31

Parâmetros

• empresa: Código da Licença.
• inicio_periodo / fim_periodo: período no formato AAAA-MM-DD.
• tipo_periodo: vencimento (padrão), cancelamento, pagamento, lançamento ou renegociacao.
• id: ID da conta a receber. Ao filtrar por ID, os demais parâmetros são ignorados.
• page / perPage: paginação (máximo 100 por página).
• documento: número do documento.
• renegociacao: data da renegociação da conta.

Campos retornados (cada parcela em data)

• id, numero_parcela, vencimento, forma_pagamento, situacao.
• valor_original, juros, multa, desconto, valor_reajustado, valor_pago.
• baixado_por / baixado_em, estornado_por / estornado_em / motivo_estorno, cancelado_por / cancelado_em / motivo_cancelamento.
• titulo: id, numero_documento, descricao, qtd_parcelas e, aninhados: cliente, plano_conta, tipo_documento, forma_pagamento e venda.
• cliente (dentro de titulo): id, nome, documento, rg, telefone_principal, email_principal.
• venda (dentro de titulo): id, numero_venda, funcionario, data.
• boleto: quando houver, traz id, nosso_numero, forma_pagamento, valor, vencimento, status.
• renegociacao e dependente: dados de renegociações e dependente vinculados (quando houver).

Exemplo de retorno

{
  "currentPage": 1,
  "totalPages": 2,
  "totalItems": 2,
  "perPage": 1,
  "data": [
    {
      "id": 161,
      "numero_parcela": 1,
      "vencimento": "2025-08-31",
      "forma_pagamento": "Carné",
      "situacao": "A vencer",
      "valor_original": 10,
      "juros": 0,
      "multa": 0,
      "desconto": 0,
      "valor_reajustado": 10,
      "valor_pago": null,
      "baixado_por": null,
      "baixado_em": null,
      "estornado_por": null,
      "estornado_em": null,
      "motivo_estorno": null,
      "cancelado_por": null,
      "cancelado_em": null,
      "motivo_cancelamento": null,
      "titulo": {
        "id": 24,
        "numero_documento": "1",
        "descricao": "Venda Crediário",
        "qtd_parcelas": 5,
        "cliente": {
          "id": 2837436,
          "nome": "Lilian",
          "documento": "000.000.000-00",
          "rg": null,
          "telefone_principal": "(00) 0.0000-0000",
          "email_principal": null
        },
        "plano_conta": "Recebimento Crediário",
        "tipo_documento": "Carné",
        "forma_pagamento": "Carné",
        "venda": {
          "id": 583,
          "numero_venda": 1,
          "funcionario": "Nome do Funcionário",
          "data": "31/07/2025"
        }
      },
      "boleto": [],
      "renegociacao": [],
      "dependente": null
    }
  ]
}

7. Clientes

Aceita tanto empresa (Código da Licença) quanto cnpj.

Endpoint — GET

https://app.ssotica.com.br/api/v1/integracoes/clientes?empresa=XXXX-XXXX&page=1&perPage=30

Parâmetros

• empresa ou cnpj: identifica a empresa.
• busca: filtra por CPF/CNPJ (quando é documento) ou por nome.
• ativo_inativo: SOMENTE_ATIVO, SOMENTE_INATIVO ou AMBOS (padrão).
• cadastro_inicio / cadastro_fim: intervalo de data de cadastro (AAAA-MM-DD). Informe ambos.
• page / perPage: paginação (padrão perPage = 30, máx. 100).

Campos retornados (cada cliente em data)

• id, tipo (PF/PJ), cpf_cnpj, nome, apelido, ativo, nascimento.
• cidade, uf, telefones (lista), emails (lista), data_cadastro.

Exemplo de retorno

{
  "currentPage": 1,
  "totalPages": 4,
  "totalItems": 312,
  "perPage": 30,
  "data": [
    {
      "id": 16813359,
      "tipo": "PF",
      "cpf_cnpj": "000.000.000-00",
      "nome": "João da Silva",
      "apelido": "Jô",
      "ativo": true,
      "nascimento": "1956-05-01",
      "cidade": "Cruz",
      "uf": "CE",
      "telefones": [ "(88) 9.0000-0000" ],
      "emails": [ "exemplo@email.com" ],
      "data_cadastro": "2022-05-31 11:44:56"
    }
  ]
}

8. Funcionários

Endpoint — GET

https://app.ssotica.com.br/api/v1/integracoes/funcionarios?empresa=XXXX-XXXX&page=1&perPage=30

Parâmetros

• empresa ou cnpj: identifica a empresa.
• busca: filtra por CPF (quando é documento) ou por nome.
• ativo_inativo: SOMENTE_ATIVO, SOMENTE_INATIVO ou AMBOS (padrão).
• funcao_id: ID da função/cargo.
• page / perPage: paginação (padrão perPage = 30, máx. 100).

Campos retornados (cada funcionário em data)

• id, nome, cpf (somente números), ativo, funcao.
• telefone_fixo, telefone_movel, cidade, uf, data_cadastro.

Exemplo de retorno

{
  "currentPage": 1,
  "totalPages": 1,
  "totalItems": 8,
  "perPage": 30,
  "data": [
    {
      "id": 105287,
      "nome": "Maria Aparecida",
      "cpf": "00000000000",
      "ativo": true,
      "funcao": "Vendedor",
      "telefone_fixo": "",
      "telefone_movel": "(88) 9.0000-0000",
      "cidade": "Cruz",
      "uf": "CE",
      "data_cadastro": "2021-03-10 09:12:00"
    }
  ]
}

9. Formas de Pagamento

Endpoint — GET

https://app.ssotica.com.br/api/v1/integracoes/formas-pagamento?empresa=XXXX-XXXX&page=1&perPage=30

Parâmetros

• empresa ou cnpj: identifica a empresa.
• busca: filtra pela descrição da forma de pagamento.
• ativo_inativo: SOMENTE_ATIVO, SOMENTE_INATIVO ou AMBOS (padrão).
• page / perPage: paginação (padrão perPage = 30, máx. 100).

Campos retornados (cada forma de pagamento em data)

• id, descricao, ativo.
• tipo_pagamento_id, tipo_pagamento, conta.
• taxa_administracao, tarifa, qtde_dias_credito.
• percentual_juros_mes_atraso, percentual_multa_mes_atraso, dias_carencia_atraso.
• metodo_calculo_taxas, configuracao_taxas (configurações detalhadas de taxas).

Exemplo de retorno

{
  "currentPage": 1,
  "totalPages": 1,
  "totalItems": 12,
  "perPage": 30,
  "data": [
    {
      "id": 51976,
      "descricao": "Cartão de Crédito Parcelado 2 a 6x",
      "ativo": true,
      "tipo_pagamento_id": 3,
      "tipo_pagamento": "Cartão de Crédito/Débito",
      "conta": "Banco",
      "taxa_administracao": 2.5,
      "tarifa": 0,
      "percentual_juros_mes_atraso": 0,
      "percentual_multa_mes_atraso": 0,
      "dias_carencia_atraso": 0,
      "qtde_dias_credito": 30,
      "metodo_calculo_taxas": "PADRAO",
      "configuracao_taxas": []
    }
  ]
}

10. Saldos das Contas

Retorna o saldo de cada conta financeira ativa da empresa e o saldo consolidado, numa data de referência. Não é paginado.

Endpoint — GET

https://app.ssotica.com.br/api/v1/integracoes/financeiro/saldos?empresa=XXXX-XXXX&data=2026-06-30

Parâmetros

• empresa ou cnpj: identifica a empresa.
• data: data de referência do saldo (AAAA-MM-DD). Padrão: data atual.

Campos retornados

• data_referencia: data considerada no cálculo.
• saldo_total: somatório do saldo de todas as contas ativas.
• contas: lista com id, descricao e saldo de cada conta.

Exemplo de retorno

{
  "data_referencia": "2026-06-30",
  "saldo_total": 18540.75,
  "contas": [
    { "id": 26407, "descricao": "Banco", "saldo": 15230.50 },
    { "id": 26408, "descricao": "Caixa", "saldo": 3310.25 }
  ]
}

➡️ Para acessar materiais técnicos de apoio à equipe de Desenvolvimento (DEVs), utilize o link: https://apidocs.ipe.digital/