Documentação da API Contotal

Visão Geral

Bem-vindo à documentação da API Contotal! Nossa API permite que empresas e usuários interajam com a plataforma Contotal de maneira eficaz e segura. Através dessa API, você pode acessar diversas funcionalidades que ajudam a gerenciar e automatizar processos relacionados aos seus negócios.

Autenticação

Para garantir a segurança e a privacidade dos dados, a API Contotal utiliza autenticação baseada em tokens. Cada requisição à API deve incluir um token de autenticação válido, que pode ser obtido através do endpoint de login. Adicione o token no header da seguinte forma:

Authorization: Bearer SEU_TOKEN_AQUI

Limite de Taxa

Para garantir o bom funcionamento e a disponibilidade da API, limitamos o número de chamadas que podem ser feitas do mesmo IP. O limite é de até 50 chamadas por minuto.

Endereço da API

O endereço base da API é:

https://pdv.contotal.com.br/api/v2

Endpoints Principais

A documentação detalhada dos endpoints está organizada em categorias, incluindo exemplos de requisições e respostas para ajudar você a começar rapidamente. Alguns dos principais endpoints incluem:

• /sales: Gerenciamento de vendas
• /payments: Controle de pagamentos
• /reports: Acesso a relatórios financeiros
• /users: Cadastro e gerenciamento de usuários
• /companies: Cadastro e gerenciamento de empresas

Estrutura das Requisições

A API Contotal segue padrões RESTful, utilizando métodos HTTP para interagir com os recursos:

• GET para recuperar dados
• POST para criar novos registros
• PUT para atualizar registros existentes
• DELETE para remover registros

Todas as respostas da API são retornadas em formato JSON, facilitando a integração e manipulação dos dados em diversas linguagens de programação.

Recuperar Vendas

Para recuperar as vendas de uma loja, faça uma chamada para a rota /sales. Se o parâmetro DATE não for passado, será retornado um JSON com as vendas do dia por padrão. Caso o parâmetro seja informado, será retornado as vendas do dia informado. Lembre-se que as informações podem ter um período de retenção que é acordado com o cliente da aplicação.

Exemplo de Requisição

Requisição sem o parâmetro DATE:

curl -X GET https://pdv.contotal.com.br/api/v2/sales \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json"

Requisição com o parâmetro DATE:

curl -X GET "https://pdv.contotal.com.br/api/v2/sales?DATE=2024-05-27" \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json"

Exemplo de Resposta

{
    "sales": [
        {
            "id": 1,
            "date": "2024-05-27",
            "total_amount": 150.00,
            "items": [
                {
                    "product_id": 101,
                    "quantity": 2,
                    "price": 50.00
                }
            ]
        },
        {
            "id": 2,
            "date": "2024-05-27",
            "total_amount": 200.00,
            "items": [
                {
                    "product_id": 102,
                    "quantity": 1,
                    "price": 200.00
                }
            ]
        }
    ]
}

Gerenciamento de Pagamentos

Para controlar os pagamentos, utilize a rota /payments. Esta rota permite criar, atualizar, listar e excluir pagamentos relacionados às vendas.

Listar Pagamentos

Para listar todos os pagamentos, utilize o método GET:

curl -X GET https://pdv.contotal.com.br/api/v2/payments \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json"

Exemplo de Resposta

{
    "payments": [
        {
            "id": 1,
            "sale_id": 1,
            "amount": 150.00,
            "method": "Credit Card",
            "date": "2024-05-27"
        },
        {
            "id": 2,
            "sale_id": 2,
            "amount": 200.00,
            "method": "Cash",
            "date": "2024-05-27"
        }
    ]
}

Criar Pagamento

Para criar um novo pagamento, utilize o método POST:

curl -X POST https://pdv.contotal.com.br/api/v2/payments \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json" \
-d '{
    "sale_id": 1,
    "amount": 150.00,
    "method": "Credit Card",
    "date": "2024-05-27"
}'

Acesso a Relatórios Financeiros

Para acessar relatórios financeiros, utilize a rota /reports. Esta rota permite obter diversos tipos de relatórios sobre as vendas e pagamentos.

Obter Relatório de Vendas

Para obter um relatório de vendas, utilize o método GET:

curl -X GET https://pdv.contotal.com.br/api/v2/reports/sales \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json"

Exemplo de Resposta

{
    "report": {
        "total_sales": 350.00,
        "total_transactions": 2,
        "sales_by_method": {
            "Credit Card": 150.00,
            "Cash": 200.00
        }
    }
}

Gerenciamento de Usuários

Para gerenciar usuários, utilize a rota /users. Esta rota permite criar, atualizar, listar e excluir usuários da plataforma.

Listar Usuários

Para listar todos os usuários, utilize o método GET:

curl -X GET https://pdv.contotal.com.br/api/v2/users \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json"

Exemplo de Resposta

{
    "users": [
        {
            "id": 1,
            "name": "João Silva",
            "email": "joao.silva@example.com",
            "role": "Admin",
            "created_at": "2024-05-01"
        },
        {
            "id": 2,
            "name": "Maria Santos",
            "email": "maria.santos@example.com",
            "role": "User",
            "created_at": "2024-05-05"
        }
    ]
}

Criar Usuário

Para criar um novo usuário, utilize o método POST:

curl -X POST https://pdv.contotal.com.br/api/v2/users \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json" \
-d '{
    "name": "Carlos Oliveira",
    "email": "carlos.oliveira@example.com",
    "password": "senha_secreta",
    "role": "User"
}'

Gerenciamento de Empresas

Para gerenciar empresas, utilize a rota /companies. Esta rota permite criar, atualizar, listar e excluir empresas cadastradas na plataforma.

Listar Empresas

Para listar todas as empresas, utilize o método GET:

curl -X GET https://pdv.contotal.com.br/api/v2/companies \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json"

Exemplo de Resposta

{
    "companies": [
        {
            "id": 1,
            "name": "Empresa A",
            "address": "Rua A, 123",
            "created_at": "2024-01-15"
        },
        {
            "id": 2,
            "name": "Empresa B",
            "address": "Avenida B, 456",
            "created_at": "2024-03-20"
        }
    ]
}

Criar Empresa

Para criar uma nova empresa, utilize o método POST:

curl -X POST https://pdv.contotal.com.br/api/v2/companies \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json" \
-d '{
    "name": "Empresa C",
    "address": "Rua C, 789"
}'

Suporte e Contato

Estamos aqui para ajudar! Se você tiver dúvidas ou encontrar problemas ao usar a API, entre em contato com nossa equipe de suporte. Fornecemos assistência rápida e eficiente para garantir que você aproveite ao máximo os recursos da Contotal.