Crear Documentos Internos

Pruebas
Producción

Dominio: https://test-api-factura.edw-dev.com

Documentación para la creación de documentos internos como presupuestos, proformas y órdenes de trabajo que no requieren autorización del SRI.

Crear Presupuesto

Crea un nuevo presupuesto o documento interno.

Endpoint

POST /api/v1/documents/create

Headers requeridos

Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}

Parámetros del cuerpo

{
  "customer": {
    "identification_type": "04",
    "identification": "0999999999001",
    "business_name": "EMPRESA DE PRUEBA S.A.",
    "address": "Av. Principal 123",
    "phone": "04-2345678",
    "email": "[email protected]"
  },
  "document_type": "PRESU",
  "establishment": "001",
  "emission_point": "001",
  "currency": "USD",
  "issue_date": "2024-01-15",
  "due_date": "2024-02-15",
  "payment_method": "01",
  "items": [
    {
      "main_code": "PROD001",
      "auxiliary_code": "AUX001",
      "description": "Producto de ejemplo",
      "quantity": 2,
      "unit_price": 100.00,
      "discount": 0.00,
      "taxes": [
        {
          "code": "2",
          "percentage_code": "2",
          "rate": 12,
          "taxable_base": 200.00,
          "tax_value": 24.00
        }
      ]
    }
  ],
  "additional_info": {
    "observaciones": "Presupuesto válido por 30 días",
    "condiciones": "Precios sujetos a cambio sin previo aviso"
  }
}

Respuesta exitosa (201 Created)

{
  "id": "12345",
  "sequential": "001-001-000000123",
  "document_type": "PRESU",
  "status": "draft",
  "customer": {
    "identification_type": "04",
    "identification": "0999999999001",
    "business_name": "EMPRESA DE PRUEBA S.A.",
    "address": "Av. Principal 123",
    "phone": "04-2345678",
    "email": "[email protected]"
  },
  "totals": {
    "subtotal_0": 0.00,
    "subtotal_12": 200.00,
    "subtotal_14": 0.00,
    "iva_12": 24.00,
    "iva_14": 0.00,
    "ice": 0.00,
    "total": 224.00
  },
  "issue_date": "2024-01-15",
  "due_date": "2024-02-15",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Ejemplos de Implementación

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/documents/create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "customer": {
      "identification_type": "04",
      "identification": "0999999999001",
      "business_name": "EMPRESA DE PRUEBA S.A.",
      "address": "Av. Principal 123",
      "phone": "04-2345678",
      "email": "[email protected]"
    },
    "document_type": "PRESU",
    "establishment": "001",
    "emission_point": "001",
    "currency": "USD",
    "issue_date": "2024-01-15",
    "due_date": "2024-02-15",
    "payment_method": "01",
    "items": [
      {
        "main_code": "PROD001",
        "auxiliary_code": "AUX001",
        "description": "Producto de ejemplo",
        "quantity": 2,
        "unit_price": 100.00,
        "discount": 0.00,
        "taxes": [
          {
            "code": "2",
            "percentage_code": "2",
            "rate": 12,
            "taxable_base": 200.00,
            "tax_value": 24.00
          }
        ]
      }
    ],
    "additional_info": {
      "observaciones": "Presupuesto válido por 30 días",
      "condiciones": "Precios sujetos a cambio sin previo aviso"
    }
  }'

<?php

use Illuminate\Support\Facades\Http;

$token = 'your-api-token';

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->post('https://dev-facturacion.e-dinky.test/api/v1/documents/create', [
    'customer' => [
        'identification_type' => '04',
        'identification' => '0999999999001',
        'business_name' => 'EMPRESA DE PRUEBA S.A.',
        'address' => 'Av. Principal 123',
        'phone' => '04-2345678',
        'email' => '[email protected]'
    ],
    'document_type' => 'PRESU',
    'establishment' => '001',
    'emission_point' => '001',
    'currency' => 'USD',
    'issue_date' => '2024-01-15',
    'due_date' => '2024-02-15',
    'payment_method' => '01',
    'items' => [
        [
            'main_code' => 'PROD001',
            'auxiliary_code' => 'AUX001',
            'description' => 'Producto de ejemplo',
            'quantity' => 2,
            'unit_price' => 100.00,
            'discount' => 0.00,
            'taxes' => [
                [
                    'code' => '2',
                    'percentage_code' => '2',
                    'rate' => 12,
                    'taxable_base' => 200.00,
                    'tax_value' => 24.00
                ]
            ]
        ]
    ],
    'additional_info' => [
        'observaciones' => 'Presupuesto válido por 30 días',
        'condiciones' => 'Precios sujetos a cambio sin previo aviso'
    ]
]);

if ($response->successful()) {
    $document = $response->json();
    echo "Presupuesto creado: " . $document['id'];
    echo "Secuencial: " . $document['sequential'];
    echo "Total: $" . $document['totals']['total'];
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

const createBudget = async () => {
    const token = 'your-api-token';

    const config = {
        method: 'post',
        url: 'https://dev-facturacion.e-dinky.test/api/v1/documents/create',
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        data: {
            customer: {
                identification_type: '04',
                identification: '0999999999001',
                business_name: 'EMPRESA DE PRUEBA S.A.',
                address: 'Av. Principal 123',
                phone: '04-2345678',
                email: '[email protected]'
            },
            document_type: 'PRESU',
            establishment: '001',
            emission_point: '001',
            currency: 'USD',
            issue_date: '2024-01-15',
            due_date: '2024-02-15',
            payment_method: '01',
            items: [
                {
                    main_code: 'PROD001',
                    auxiliary_code: 'AUX001',
                    description: 'Producto de ejemplo',
                    quantity: 2,
                    unit_price: 100.00,
                    discount: 0.00,
                    taxes: [
                        {
                            code: '2',
                            percentage_code: '2',
                            rate: 12,
                            taxable_base: 200.00,
                            tax_value: 24.00
                        }
                    ]
                }
            ],
            additional_info: {
                observaciones: 'Presupuesto válido por 30 días',
                condiciones: 'Precios sujetos a cambio sin previo aviso'
            }
        }
    };

    try {
        const response = await axios(config);
        console.log('Presupuesto creado:', response.data.id);
        console.log('Secuencial:', response.data.sequential);
        console.log('Total: $', response.data.totals.total);
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

// Uso
createBudget()
    .then(result => console.log('Éxito:', result))
    .catch(error => console.error('Error:', error));

Convertir Presupuesto

Convierte un presupuesto existente en una factura oficial.

Endpoint

POST /api/v1/documents/{id}/convert

Headers requeridos

Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}

Parámetros del cuerpo

{
  "document_type": "01",
  "establishment": "001",
  "emission_point": "001",
  "environment": "TEST",
  "issue_date": "2024-01-15",
  "payment_method": "20",
  "additional_info": {
    "observaciones": "Factura generada desde presupuesto"
  }
}

Respuesta exitosa (201 Created)

{
  "id": "12346",
  "sequential": "001-001-000000124",
  "document_type": "01",
  "status": "draft",
  "environment": "TEST",
  "customer": {
    "identification_type": "04",
    "identification": "0999999999001",
    "business_name": "EMPRESA DE PRUEBA S.A.",
    "address": "Av. Principal 123",
    "phone": "04-2345678",
    "email": "[email protected]"
  },
  "totals": {
    "subtotal_0": 0.00,
    "subtotal_12": 200.00,
    "subtotal_14": 0.00,
    "iva_12": 24.00,
    "iva_14": 0.00,
    "ice": 0.00,
    "total": 224.00
  },
  "original_document_id": "12345",
  "issue_date": "2024-01-15",
  "created_at": "2024-01-15T11:00:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}

Respuesta de error (404 Not Found)

{
  "error": "Document not found",
  "message": "El documento con ID 12345 no fue encontrado",
  "code": "DOCUMENT_NOT_FOUND"
}

Ejemplos de Implementación

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/documents/12345/convert" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "document_type": "01",
    "establishment": "001",
    "emission_point": "001",
    "environment": "TEST",
    "issue_date": "2024-01-15",
    "payment_method": "20",
    "additional_info": {
      "observaciones": "Factura generada desde presupuesto"
    }
  }'

<?php

use Illuminate\Support\Facades\Http;

$token = 'your-api-token';
$documentId = '12345';

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->post("https://dev-facturacion.e-dinky.test/api/v1/documents/{$documentId}/convert", [
    'document_type' => '01',
    'establishment' => '001',
    'emission_point' => '001',
    'environment' => 'TEST',
    'issue_date' => '2024-01-15',
    'payment_method' => '20',
    'additional_info' => [
        'observaciones' => 'Factura generada desde presupuesto'
    ]
]);

if ($response->successful()) {
    $invoice = $response->json();
    echo "Factura creada: " . $invoice['id'];
    echo "Secuencial: " . $invoice['sequential'];
    echo "Total: $" . $invoice['totals']['total'];
    echo "Documento original: " . $invoice['original_document_id'];
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

const convertBudgetToInvoice = async (documentId) => {
    const token = 'your-api-token';

    const config = {
        method: 'post',
        url: `https://dev-facturacion.e-dinky.test/api/v1/documents/${documentId}/convert`,
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        data: {
            document_type: '01',
            establishment: '001',
            emission_point: '001',
            environment: 'TEST',
            issue_date: '2024-01-15',
            payment_method: '20',
            additional_info: {
                observaciones: 'Factura generada desde presupuesto'
            }
        }
    };

    try {
        const response = await axios(config);
        console.log('Factura creada:', response.data.id);
        console.log('Secuencial:', response.data.sequential);
        console.log('Total: $', response.data.totals.total);
        console.log('Documento original:', response.data.original_document_id);
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

// Uso
convertBudgetToInvoice('12345')
    .then(result => console.log('Éxito:', result))
    .catch(error => console.error('Error:', error));

Tipos de documentos internos

PRESU - Presupuesto

Descripción: Cotización o presupuesto para el cliente
Validez: Definida por el usuario
Conversión: Puede convertirse a factura oficial
Estado: Siempre permanece como “draft”

PROFORMA - Proforma

Descripción: Documento informativo de venta
Validez: Sin validez fiscal
Conversión: Puede convertirse a factura oficial
Estado: Siempre permanece como “draft”

OT - Orden de Trabajo

Descripción: Documento interno para control de servicios
Validez: Solo para uso interno
Conversión: Puede convertirse a factura oficial
Estado: Puede tener estados internos personalizados

Campos específicos para documentos internos

Información adicional común

observaciones: Notas generales del documento
condiciones: Términos y condiciones
validez: Tiempo de validez del presupuesto
descuentos_generales: Descuentos aplicables
forma_pago: Condiciones de pago

Validaciones

Los documentos internos no requieren validación del SRI
Los campos de cliente son opcionales para algunos tipos
Los totales deben cuadrar matemáticamente
Las fechas no pueden ser futuras (excepto fecha de vencimiento)

Códigos de error comunes

400 - Datos inválidos en la solicitud
401 - Token de autorización inválido
403 - Sin permisos para crear documentos
404 - Documento no encontrado (para conversión)
422 - Error de validación de datos
500 - Error interno del servidor

Notas importantes

Los documentos internos no se envían al SRI
Pueden ser convertidos a documentos oficiales posteriormente
Los secuenciales son independientes de los documentos del SRI
Se pueden modificar libremente mientras mantengan estado “draft”
Ideales para procesos de cotización y presupuestación