Primeros pasos

La API de Gravitas e-CF permite que tu ERP emita y consulte comprobantes fiscales electrónicos (e-CF), reciba los e-CF de tus proveedores y se entere de cada cambio por webhooks. Esta guía te lleva de cero a tu primer e-CF aceptado por la DGII en el ambiente de pruebas.

1. Crea tu cuenta de prueba

Regístrate en gravitastec.com/registro. Tienes 14 días contra los ambientes de pruebas de la DGII (TesteCF y CerteCF). Tu cuenta tendrá una dirección propia, por ejemplo https://tuempresa.gravitastec.com, que es también la URL base de la API: https://tuempresa.gravitastec.com/api/v1.

2. Prepara tu empresa

En el portal, registra tu empresa (RNC), carga su certificado digital para procesos tributarios y delega a Gravitas en la Oficina Virtual de la DGII. La lista de verificación de la empresa te indica qué falta. Mientras tanto, la empresa trabaja en TesteCF.

3. Crea una credencial de API

En el portal, abre API / Desarrolladores → Credenciales y crea una credencial para tu empresa en el ambiente de pruebas. El secreto se muestra una sola vez: guárdalo en el almacén de secretos de tu ERP. Consulta Autenticación y tokens.

4. Obtén un token

curl

# Obtener un token de acceso (válido 15 minutos). Reemplace YOUR_CLIENT_SECRET por su secreto.
curl -s -X POST "https://tuempresa.gravitastec.com/api/v1/oauth/token" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"
# Guarde el valor de access_token: export TOKEN=...

C#

// Obtener un token de acceso (válido 15 minutos).
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var api = new HttpClient { BaseAddress = new Uri("https://tuempresa.gravitastec.com/api/v1/") };
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["client_id"] = "YOUR_CLIENT_ID",
    ["client_secret"] = Environment.GetEnvironmentVariable("GRAVITAS_CLIENT_SECRET") ?? "YOUR_CLIENT_SECRET",
});
var tokenResponse = await api.PostAsync("oauth/token", form);
tokenResponse.EnsureSuccessStatusCode();
var token = JsonDocument.Parse(await tokenResponse.Content.ReadAsStringAsync()).RootElement.GetProperty("access_token").GetString();
api.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
Console.WriteLine("Token obtenido; expira en 15 minutos.");

JavaScript

// Obtener un token de acceso (válido 15 minutos). Node 20+.
const baseUrl = 'https://tuempresa.gravitastec.com/api/v1';
const tokenResponse = await fetch(`${baseUrl}/oauth/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: process.env.GRAVITAS_CLIENT_SECRET ?? 'YOUR_CLIENT_SECRET',
  }),
});
const { access_token: token } = await tokenResponse.json();
const auth = { Authorization: `Bearer ${token}` };
console.log('Token obtenido');

5. Emite tu primer e-CF

curl

# Emitir un e-CF 31 en test para la empresa 101000001 (respuesta 202 con documentId de Gravitas).
curl -s -X POST "https://tuempresa.gravitastec.com/api/v1/companies/0192f1a0-0000-7000-8000-000000000001/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: pedido-0001" \
  -H "Content-Type: application/json" \
  -d '{
  "ecfType": 31,
  "issueDate": "2026-11-02",
  "incomeType": "01",
  "paymentType": 1,
  "buyer": { "rnc": "101672919", "name": "CLIENTE DE PRUEBA SRL" },
  "lines": [
    { "itemName": "Servicio de transporte", "isService": true, "billingIndicator": 1, "quantity": 1, "unitPrice": 1000 }
  ]
}'

C#

// Emitir un e-CF 31 en test para la empresa 101000001.
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var api = new HttpClient { BaseAddress = new Uri("https://tuempresa.gravitastec.com/api/v1/") };
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["client_id"] = "YOUR_CLIENT_ID",
    ["client_secret"] = Environment.GetEnvironmentVariable("GRAVITAS_CLIENT_SECRET") ?? "YOUR_CLIENT_SECRET",
});
var tokenResponse = await api.PostAsync("oauth/token", form);
tokenResponse.EnsureSuccessStatusCode();
var token = JsonDocument.Parse(await tokenResponse.Content.ReadAsStringAsync()).RootElement.GetProperty("access_token").GetString();
api.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var request = new HttpRequestMessage(HttpMethod.Post, "companies/0192f1a0-0000-7000-8000-000000000001/documents")
{
    Content = new StringContent("""
        {
          "ecfType": 31,
          "issueDate": "2026-11-02",
          "incomeType": "01",
          "paymentType": 1,
          "buyer": { "rnc": "101672919", "name": "CLIENTE DE PRUEBA SRL" },
          "lines": [
            { "itemName": "Servicio de transporte", "isService": true, "billingIndicator": 1, "quantity": 1, "unitPrice": 1000 }
          ]
        }
        """, System.Text.Encoding.UTF8, "application/json"),
};
request.Headers.Add("Idempotency-Key", "pedido-0001");
var response = await api.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

JavaScript

// Emitir un e-CF 31 en test para la empresa 101000001. Node 20+.
const baseUrl = 'https://tuempresa.gravitastec.com/api/v1';
const tokenResponse = await fetch(`${baseUrl}/oauth/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: process.env.GRAVITAS_CLIENT_SECRET ?? 'YOUR_CLIENT_SECRET',
  }),
});
const { access_token: token } = await tokenResponse.json();
const auth = { Authorization: `Bearer ${token}` };

const response = await fetch(`${baseUrl}/companies/0192f1a0-0000-7000-8000-000000000001/documents`, {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json', 'Idempotency-Key': 'pedido-0001' },
  body: JSON.stringify({
    "ecfType": 31,
    "issueDate": "2026-11-02",
    "incomeType": "01",
    "paymentType": 1,
    "buyer": { "rnc": "101672919", "name": "CLIENTE DE PRUEBA SRL" },
    "lines": [
      { "itemName": "Servicio de transporte", "isService": true, "billingIndicator": 1, "quantity": 1, "unitPrice": 1000 }
    ]
  }),
});
console.log(response.status, await response.json());

La respuesta 202 Accepted trae el documentId de Gravitas. El documento se valida contra el XSD oficial, se firma, se envía a la DGII y se consulta su estado en segundo plano.

6. Consulta el estado

curl

# Consultar el estado de un documento (use el id devuelto al emitir).
curl -s "https://tuempresa.gravitastec.com/api/v1/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $TOKEN"

C#

// Consultar el estado de un documento.
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var api = new HttpClient { BaseAddress = new Uri("https://tuempresa.gravitastec.com/api/v1/") };
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["client_id"] = "YOUR_CLIENT_ID",
    ["client_secret"] = Environment.GetEnvironmentVariable("GRAVITAS_CLIENT_SECRET") ?? "YOUR_CLIENT_SECRET",
});
var tokenResponse = await api.PostAsync("oauth/token", form);
tokenResponse.EnsureSuccessStatusCode();
var token = JsonDocument.Parse(await tokenResponse.Content.ReadAsStringAsync()).RootElement.GetProperty("access_token").GetString();
api.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var documentId = args[0]; // id devuelto al emitir
var document = await api.GetFromJsonAsync<JsonElement>($"documents/{documentId}");
Console.WriteLine(document.GetProperty("status"));

JavaScript

// Consultar el estado de un documento. Node 20+.
const baseUrl = 'https://tuempresa.gravitastec.com/api/v1';
const tokenResponse = await fetch(`${baseUrl}/oauth/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: process.env.GRAVITAS_CLIENT_SECRET ?? 'YOUR_CLIENT_SECRET',
  }),
});
const { access_token: token } = await tokenResponse.json();
const auth = { Authorization: `Bearer ${token}` };

const documentId = process.argv[2]; // id devuelto al emitir
const document = await (await fetch(`${baseUrl}/documents/${documentId}`, { headers: auth })).json();
console.log(document.status);

Cuando el estado sea accepted, descarga el XML firmado exacto con la operación /documents/{documentId}/xml. Para enterarte sin consultar, configura un webhook.

Siguientes pasos

• Ambientes: de TesteCF a producción.
• Emitir e-CF: los 10 tipos, impuestos y notas de crédito.
• Referencia de la API: todas las operaciones. También puedes descargar el OpenAPI.